Import XML | Version 3

Importing Users and Roles

How to import Sophora users and roles.

Archived documentation for Sophora 3. End-of-support date for this version: 7/25/21

Documentation for Sophora 4

Importing Roles

To import roles, the root element of an import XML file has to be <sophora>. This element must contain a child element <roles> which encapsulate the <role> elements. Each <role> element represents one role to import. A role is identified by his roleId (since version 2.4 of the Sophora-Import Xml. In older versions, the name is the identifier. Since 2.4 the name must be unique. If a role with the given name already exists, but with a different roleId, the import will fail.). If a role with the given roleId already exists it will be overwritten with the role specified in the XML. A role consists of the parts <systemPermissions>, <structureNodePermission>, <documentPermissions>, <tabPermissions> and <proposalSectionPermissions>. For further information about these permissions see the documentation for administrators. All of these permissions consist of a set of concrete permissions. If a role grants e.g. all system permissions, not every permission needs to be mentioned in the xml. Instead the pseudo permission 'all' can be used.

A structure permission specifies the individual permissions per structure node. These permissions can be passed to sub nodes by using the attribute  applyToAllSubNodes="true".

If the role exists, the permissions are overwritten. After the import, the role will have only the permissions from the import XML. If e.g. a proposal section exists in the repository but is not mentioned in the import XML, or has no <permission> elements in the XML, the role will have no permissions for it after the import.

If referenced nodetypes or referenced structure nodes do not exist, they are ignored.

The following example shows an import XML for importing a role:

<?xml version="1.0" encoding="UTF-8"?>
<sophora xmlns="http://www.sophoracms.com/import/2.8"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
[...]
 <roles>
    [...]
    <role name="example" roleId="exampleRoleId">
      <systemPermissions>
        <permission>breakLock</permission>
        <permission>editCategory</permission>
        <permission>editHtmlParagraph</permission>
      </systemPermissions>
 
      <structureNodePermissions>
        <structureNodePermission structureNode="/demosite">
          <permission>all</permission>
        </structureNodePermission>
        <structureNodePermission structureNode="/demosite/home">
          <permission>editStructure</permission>
          <permission>editNavigation</permission>
          <permission>editConfiguration</permission>
        </structureNodePermission>
        <structureNodePermission structureNode="/demosite/trendcities" applyToAllSubNodes="true">
          <permission>readDocuments</permission>
        </structureNodePermission>
       [...]
       </structureNodePermissions>
 
      <documentPermissions>
        <documentPermission nodetype="sophora-content-nt:story">
          <permission>all</permission>
        </documentPermission>
        <documentPermission nodetype="sophora-demo-nt:basicfields">
          <permission>release</permission>
          <permission>publish</permission>
          <permission>restore</permission>
          <permission>delete</permission>
          <permission>save</permission>
          <permission>create</permission>
          <permission>read</permission>
        </documentPermission>
        <documentPermission nodetype="sophora-content-nt:filter">
          <permission>restore</permission>
          <permission>delete</permission>
        </documentPermission>
        [...]
      </documentPermissions>
 
      <tabPermissions>
        <tabPermission tabExternalId="6729d6b8-cd5b-3de4-b835-0963e3062d44">
          <permission>all</permission>
        </tabPermission>
        <tabPermission tabExternalId="56dc55eb-56c8-34b2-8fe9-39956895bb36">
          <permission>readTab</permission>
        </tabPermission>
        <tabPermission tabExternalId="external_id_tab_0001">
          <permission>readTab</permission>
        </tabPermission>
        [...]
      </tabPermissions>
 
      <proposalSectionPermissions>
        <proposalSectionPermission>
          <proposalSection>
            <path>homepage</path>
          </proposalSection>
          <permission>readProposals</permission>
        </proposalSectionPermission>
        <proposalSectionPermission>
           <proposalSection>
            <path>homepage</path>
            <path>readtopublish</path>
          </proposalSection>
        <permission>addProposals</permission>
        </proposalSectionPermission>
        <proposalSectionPermission>
          <proposalSection>
            <path>news</path>
          </proposalSection>
        <permission>all</permission>
        </proposalSectionPermission>
        <proposalSectionPermission>
          <proposalSection>
            <path>news</path>
            <path>sport</path>
          </proposalSection>
          <permission>readProposals</permission>
          <permission>editProposals</permission>
          <permission>addProposals</permission>
        </proposalSectionPermission>
        <proposalSectionPermission>
          <proposalSection>
            <path>news</path>
            <path>sport</path>
            <path>handball</path>
          </proposalSection>
          <permission>readProposals</permission>
          <permission>editProposals</permission>
        </proposalSectionPermission>
        <proposalSectionPermission applyToAllSubSections="true">
          <proposalSection>
            <path>news</path>
            <path>sport<path>
            <path>bundesliga<path>
          </proposalSection>
          <permission>readProposals</permission>
          <permission>editProposals</permission>
          <permission>addProposals</permission>
        </proposalSectionPermission>
      </proposalSectionPermissions>
    </role>
    [...]
  </roles>
</sophora>

Permissions

The following sections shows the different permissions and their valid values.

System permissions

  • administrator
  • breakLock
  • deleteReferenced
  • deleteFromTrash
  • editCategory
  • editHtmlParagraph
  • finishPrePublish
  • massImageUpload
  • massOperations
  • setOfflineReferenced
  • all

Structure permissions

  • editDocuments
  • readDocuments
  • editStructure
  • editNavigation
  • editConfiguration
  • publishDefaultDocument
  • all

Document permissions

  • release
  • publish
  • restore
  • delete
  • save
  • create
  • read
  • offline
  • clone
  • protect
  • all

Tab permissions

  • readTab
  • editTab
  • all

Proposal Section permissions

  • readProposals
  • editProposals
  • addProposals
  • deleteProposals
  • all

Importing Users

To import users, the root element of an import XML file has to be <sophora>. This element must contain a child element <users> which encapsulate the <user> elements. Each <user> element represents one user to import. During the import process each user is identified by its name. So if a user with a given name already exists this user will be overwritten. But when a property is absent in the XML, then it is not overwritten.  Due to  security reasons the passwords are not exported per default. Nevertheless it is possible to export the password as hashes by activating the corresponding option in the export dialog. These passwords are automatically imported. Referenced roles or sites which do not exist are ignored.

The following example demonstrates the buildup of users import XML:

<?xml version="1.0" encoding="UTF-8"?>
<sophora xmlns="http://www.sophoracms.com/import/2.8"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  [...]
  <users>
    <user>
      <username>doe</username>
      <passwordChangeable>true</passwordChangeable>
      <firstName>John</firstName>
      <lastName>Doe</lastName>
      <comment>comment</comment>
      <company>Doe Services</company>
      <department>engineering</department>
      <mail>doe@services.com</mail>
      <phone>0123456789</phone>
      <initials>j.d</initials>
      <validUntil>2099-07-26T15:32:00.000+02:00</validUntil>
      <incorrectLogins>2</incorrectLogins>
      <lastLogin>2012-09-07T09:37:53.716+02:00</lastLogin>
      <roles>
        <role name="admin" roleId="adminRoleId"/>
        <role name="ReadOnlyRole" roleId="readOnlyRoleId"/>
      </roles>
      <previews>
        <preview externalID="f3d1d72c-5667-493d-899c-338c49e65466">http://www.example.org/previewurl</preview>
        <preview externalID="550e8400-e29b-41d4-a716-446655440000">http://www.example.org/previewurl2</preview>
      </previews>
    </user>
    [...]
  </users>
  [...]
</sophora>

Last modified on 10/2/20

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.

Icon