XML Content Migration Documentation

Version 26

    Overview

    XML Content Migrations are one of several strategies for migrating customer data from legacy systems to Jive. It is primarily used for migrations from source systems for which Jive Professional Services does not offer out of the box content extraction. Customers who can and want to produce a content export of their legacy system in the Jive-specific XML format described below may chose this approach in lieu of a Jive PS engagement to implement a custom content extractor.

     

    XML Migration Overview.gif

     

     

    The XML Migration Plugin is an internal framework used by Jive Professional Services to aid in customers' content migration engagements from legacy systems to Jive. The tool processes a set of XML files, which represent content exported from the customer's source platform. The high-level data flow during the actual migration is as follows:

     

     

    Getting Started

    1. Download the attached archive containing
      1. An XSD (XML Schema Definition, migration.xsd) describing the format of the expected XML
      2. The migration object type list (object-types.tab), which can be opened with MS Excel.
      3. Sample XML for each object type.
    2. Extract it and inspect the folder structure.
    3. Using the tools and possibly custom software or scripts applicable to your source system, create an XML export for one of your source object types, typically Users.
      1. Match the XML bean definition provided in the samples. You may skip attributes marked as optional in the XSD.
      2. Match the file structure, i.e. more than one bean per file, but no more than 100 MB per XML file.
      3. Match the provided folder structure exactly for each content type.
      4. Ensure that generated XML is exclusively UTF-8 encoded.
      5. Wrap non-conforming content in <![CDATA[  ... ]]> sections.
    4. Validate the generated XML using the either just the XSD or–preferably–the XML Validation Tool provided by Jive PS during the migration engagement.
    5. Repeat steps 3. and 4. for all necessary source content types.
    6. Compress all content into a single ZIP archive and send to Jive PS for review/testing.
      1. Do not use TAR and/or gzip formats.
      2. Ensure you are using the correct compression tool parameters to encode file names as UTF-8.
      3. Please be aware that Windows has a 255 character limit for file name lengths, but with the folder structure provided you should not run into that. If you do, generate XML at the root folder of a drive, such as C:\XML

     

    File Structure Requirements

    1. The names of the object type folders are mandatory–they must be these names in uppercase. Those names match the object types listed in the attachment's object-types.tab.
    2. The XML file names within each folder are arbitrary.
    3. The entire export must be compressed in a single ZIP archive, named <customer>-xml-YYYY-MM-DD-N.zip, containing the timestamp of the export and a running number N starting at 1 to support providing more than one export per day.

     

    XML Export Requirements

    Most requirements for the XML beans are encoded in the attached XSD. There are several abstract bean types defined with common element definitions, from which all other bean definitions derive. It is generally easier to start from the samples and use them as documentation rather than navigating the XSD, unless your XML tool has full XSD support.

    1. All XML file contents must start with the <importSource> tag.
    2. Each bean must have a unique Source ID among all beans of the same type. The same Source ID, however, can be reused across different types. For example there can be both a blog post and a discussion message each with the Source ID 'XYZ1042.'
    3. Any Source ID that references another bean's Source ID must actually exist in the other bean. For example, a blog post's UserID must correspond to an existing bean of type USER with that same ID.
    4. Any bean derived from containableBean must specify a container to which it belongs, which is always a combination of container type (see folder names for permissible values) and container ID.
    5. Source IDs must not be generated via some integer counter run during the XML creation. Instead, unique natural keys should be used for Source IDs. If no such key is available in the source system for a certain object type, use a compound key. For example, let's say users have GUIDs source IDs, such as '1c80715d-eb32-4230-b337-8bc27f32f8a2.' Suppose also that your source system's containers to be migrated as Social Groups in Jive use a normalized version of their name as unique source ID, for example 'getting_started_with_spark.' For migrating social group membership information, you could then use a synthetic Source ID for each socialGroupMemberBean, e.g.
      <socialGroupMember
        sourceId="getting_started_with_spark|1c80715d-eb32-4230-b337-8bc27f32f8a2"
        creationDate="1416808350474"
        containerId="getting_started_with_spark"
       
      userId="1c80715d-eb32-4230-b337-8bc27f32f8a2"
      />
    6. All dates must be provided as milliseconds since the UNIX epoch, for example '1242365364000' for 'Fri, 15 May 2009 05:29:24 GMT.'
    7. All numeric values must not contain leading zeros, i.e. not look like 00123.

     

    Object Types

    The attached object-types.tab contains a list of object types that are supported for a Jive Content Migration. The format is as follows:

     

    JIve-internal Object Type ID Object Type NameCorresponding XML Bean Name
    3USERuserBean
    2020

    USER_CONTAINER

    459125536

    USER_PROFILE_VALUE

    userProfileValueBean

    and so on.

     

    Only types that have a corresponding XML Bean Name can be migrated. All other object types are listed for reference purposes only; some of them may be needed/used when configuring the Containable Types for a Space, Social Group, or Project. The order of object types in this file is the order in which referential integrity is validated. For example, Users don't have any referential dependencies, but a User Profile Value must refer to a migrated user. Therefore, user profile values are processed after users and we check that each user profile value references a user that has been previously migrated.

     

    When referencing object types in XML, such as when specifying the type of container, use the corresponding Object Type Name.

     

    Object Type Specifics

     

    Containables

    Many object types in Jive live inside another container. Containers are Spaces (Communities), Social Groups, Projects, and Blogs. To specify the container to which a particular object type instance, such as a Document or Discussion, belongs, use:

    1. <containerType> – The type of container, such as: COMMUNITY, SOCIAL_GROUP, PROJECT, or BLOG. Only Blog Posts are allowed to be contained within Blogs. Other restriction may apply based on the "containable types" configured for a particular container.
    2. <containerID> – The Source ID of the corresponding container.

     

    User

    By default, a source users will be mapped to an existing user if there is an exact match on either username or email.

     

    Community (Space)

    The <containableTypes> element must list each type of containable type for each community, ie: DISCUSSION if you are loading discussions, DOCUMENT if you are loading documents–otherwise the discussions or documents wouldn't show once migrated. The list of valid types here is again the sample folder names. The <parentCommnityID> element should have a value of 1, unless you are loading a hierarchy of communities, in which case the ID must refer to another community bean that comes before it in the file(s).

     

    Social Group

    Containable types are handled the same as for Community.

     

    Social Group Member

    The Social Group Member object type is the way to add users to a Social Group. The user who is the owner of the Social Group is typically added as part of the Social Group XML itself, so SocialGroupMemberBean is normally used to simply add additional members and administrators to a Social Group.

     

    Project

    Projects are a unique, in that they are contained by either a Social Group or Space (Community) AND they themselves contain other content, like Documents or Blogs etc. The project may only contain content types which are allowed by its parent container.

     

    On-Prem Instructions

    The migration is initiated from the Jive admin console and thus executes in a running instance of Jive:

    1. Shut down all other nodes.
    2. Ensure EAE is up and running and healthy (in the Jive instance's admin console).
    3. Configure and execute the migration. Details on how to do so will be provided by the PS Engineer engaged on your migration project.
    4. Rebuild
      1. Browse index
      2. Content search index
    5. Restart all Jive web app nodes including the one that executed the migration.
    6. Rebuild the user search index.