Import XML | Version 4

Importing Users and Roles

How to import Sophora users and roles.

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/4.2"
         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/4.2"
         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/16/20

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

Icon