Versions Compared

Version Old Version 13 New Version Current
Changes made by

Matija Lukic (Deactivated)

Diego Faneyte

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The command-line interface is a automation-friendly executable that orchestrates obtaining access tokens. Furthermore, it provides a number of execution options to improve the locality of change, and reduce efforts to call CXO user sync API.

To see the OpenAPI specification of the User Sync API, open <cxo-url>/public/swagger (example from CXO training environment) and search for users/synchronize.

Command-line interface

The command-line interface (or CLI) provides the functionality of synchronizing the users of one or many CXO Applications with an external repository.

Prerequisite

The tool requires the .Net Core 36.1 0 runtime to be installed on the machine

Or soon .Net 8.0 runtime

Installation

The tool is distributed as a zip archive, simply unzip it in the desired location and it is ready to use.

...

You may run it from the installation folder by opening the command line and calling the executable: CXO.User.Synchronization.Client.CLI.exe

Running it in the following way will list all the options / parameters available.
./CXO.User.Synchronization.Client.CLI.exe

Parameters

Parameter

Short
hand

Description

--cxoUrl

N/A

URL of CXO

--idpUrl

N/A

URL of the CXO identity provider.

--clientId

-c

Identity provider - client Id. See the Security section on how to obtain this value.

--privateKey

-p

Identity provider - client private key. See the Security section on how to obtain this value.

--input

-i

Path of the input file. See the Inputs section.

--applicationsFile

-a

The file path to a list of applications to synchronize.

--masterDatabaseConnectionString

-m

Connection string of the master database. Using this option all applications (from given master database) will be synchronized.

If this option is set, (-a --applicationsFile) option should not be set.

--filterApplications

-f

A comma-separated list of application
names. You may use this option when (-m,
--masterDatabaseConnectionString) is
set to filter the applications to synchronize.

--maxParallelism

-P

Default(1) . Represents the max number of applications to synchronize in parallel. This value should be at most equal to the amount of CXO instances available.

--init

N/A

Initializes the input file and applicationsFile with an example text at the path specified to each parameter.

Endpoints

As described in the Deployment section, the CLI interacts with CXO. For that reason, you need to provide CXO and IDP URLs using --cxoUrl and --idpUrl options, respectivelly.

...

CLI requires the list of users with their corresponding CXO user groups to be supplied as a json file. This input is mandatory, so no passing this file will result in an error. As for the file content, for each user, the following can be specified:

Field

Optional/Mandatory

Limitations

User name

Mandatory

unique, not null, at most 300 characters

Full name

Optional

at most 2000 characters

Email

Optional

value email address format, at most 2000 characters

User groups

Mandatory

For each group: unique, not null, at most 300 characters

Additionally, if supplied with (--applicationsFile, -a), another json file will specify which applications to synchronize. As for the file content, for each application, the following can be specified:

...

This code-snippet would will automatically synchronize the applications and users from the two input json files.

Troubleshooting

Speed of executionSynchronizing users takes too much time

The time it takes to synchronize the users (i.e. run the command line) is proportional to the number of users in your CXO applications.

...

  • Run the command line interface more often to make sure not too many users are added / removed.

  • In the web application configuration (web.config file), in httpRuntime, the executionTimeout value can be increased

Synchronization fails due to DbUpdateConcurrencyException

The synchronization of CXO application users occurs within a single transaction. When a user is updated or deleted many other resources (conversations, storyboards, reports, etc..) also need to be modified. For performance reasons, CXO doesn’t lock these resources. If they are modified while the synchronization is in progress an error will occur and the transaction will be rolled back.

If this error occurs, try the following:

  • Retry

  • Make sure the user synchronization runs at a time where CXO is not in use.

  • Pause the CXO services before running the synchronization.

To pause the CXO services there are two options:

1. Stop programmatically while the user synchronization is ongoing (refer to the code snippet below).

Code Block
Stop-Service -Name "CXO-Cockpit Agent"
Stop-Service -Name "CXO-Cockpit Export Service"
<run synchronizatiob>
Stop-Service -Name "CXO-Cockpit Agent"
Stop-Service -Name "CXO-Cockpit Export Service"

2. Adjust active periods using Configurator

  • Open the Configurator > Configuration > Schedule.xml

  • Edit the cron-expression of the following jobs so that they are not run while the user synchronization is ongoing: ScreenshotsOnDemandJob, CleanUpJob

    Image Added

    You can use a CRON expression editor to define a period when the services will not be running.
    See examples below on how to pause it between 2 AM and 4 AM

    Image AddedImage Added

  • Leave time for export jobs to complete before the user synchronization begins