Documentation Center

Collective Spaces - Steps to configure

Configure your own custom DITA specialization for use with Collective Spaces, or change the out-of-the-box configuration.

Before you begin

ISHDeploy needs to be installed on the Content Manager server. The presentation and documentation for ISHDeploy can be found on GitHub: https://rws.github.io/ISHDeploy/.

If you want to configure your own custom DITA specialization, you also need your DTD and corresponding XML Schema file. As Collective Spaces uses a compiled schema format, the XML Schema is required.

Procedure

  1. If you want to change the behavior only, without adding or updating custom DITA specialization, skip ahead to step 7.
  2. Go to the Web\Author\ASP\DocTypes\ folder, where Content Manager keeps all DTD, XML Schema and catalog-related files. You will need to install the new DTD and XML Schema files there. More information here: Install DTDs/Schema's.
  3. Add entries for the new DTD and XML Schema files in the catalog.xml. More information here: Configuring the OASIS catalog.
    You can now successfully upload XML documents that refer to the new DTD in Content Manager.
  4. Add entries for the new DTD and XML Schema files in the catalog-mapping.xml file. Add a line like the following to this file:
    <match rootelement="apiref" dtdpublicid="-//SDL//DTD DITA API Reference//EN" dtdsystemid="dita-sdl/1.3/dtd/apiref/dtd/apiref.dtd" xsdsystemid="urn:sdl:names:tc:dita:spec:apiref:xsd:apiref.xsd" xsdname="" xsduri="apiref.xsd" />
  5. Replace all attribute values in this line with values that are correct for your DTD and Schema.
  6. In order to validate your schemas and configuration files and compile the schemas to a format Collective Spaces understands, start PowerShell as administrator and run the following ISHDeploy command:
    Set-ISHFontoSchemaExperience -IshDeployment InfoShare
    (You only need to use the -IshDeployment switch if you have multiple deployments. InfoShare is the name of the default deployment.) If all is correct, the command saves the resulting files in the Web\InfoShareCS\custom\ folder (overwriting the existing SchemaLocationConfig.xml file and saving the generated compiled schema files in the schemas\ subfolder) and restarts the web application pool of Collective Spaces automatically. In your browser, in Collective Spaces, you can now open a publication that contains XML documents that refers to the new DTD. You will see the out-of-the-box behavior, which is always applied to any DTD, but which might not look nice or behave well for your new DTD yet.
  7. To configure custom specialized XML elements or overwrite (parts of) the out-of-the-box configuration for the standard DITA elements, you can make additions to the BehaviorConfig.xml file, which is empty by default. More information here: BehaviorConfig.xml and here: BehaviorConfig.xml - Examples and How To
  8. After making changes to the BehaviorConfig.xml file, start PowerShell as administrator and run the following ISHDeploy command (again, if you ran it in step 6):
    Set-ISHFontoSchemaExperience -IshDeployment InfoShareAuthor
    This will validate whether your XML is correct, and if all is correct, save the SchemaLocationConfig.xml and compiled schemas, and restart the web application pool, so that you can see the result of your changes immediately (after reloading the publication in the browser).