This page has help for the XSI Repository Console. The XSI Repository Console is shipped with the .NET XSI backend and helps a developer understanding the XSI repository. The product is contained in the DemoApp project within the complete Visual Studio solution. This manual assumes you’ve got the solution checked out and have your environment setup properly.

First things first: make sure the DemoApp project is marked as the StartUp Project within the solution and run it. The console starts:

The XSI Repository Command Line Interface uses a one-statement-per-line-based interpreter and it is able to process the commands below:

• q: Quits the application (after ctrl-c)
• h: Displays help and includes a link to this page.
• v: Displays the version of the console.
• AddRegistration: Adds a subscription to the backend.
• RemoveRegistration: Removes a subscription from the backend.
• Start: Starts the repository. This initializes the session with the XSI provider.
• Suspend: Suspends the repository. Keeps the session with the XSI provider active, but terminates any subscriptions.
• Stop: Stops the backend.
• Content: Fetches the first available Repository Content from the repository and displays the content on the console.
• ActiveRegistrationCount: Displays the current number of subscriptions.
• MaintainedRegistrationCount: Displays the current number of subscriptions that are kept alive.
• MessageCount: Displays the current number of Repository Content messages.

The commands are discussed in more details in the next paragraphs.

q

q

Quits the demo application. The console still needs ctrl-c (and confirmation) to really close the console. Once closed, it will terminate the console and terminate the backend.

q

h

Displays help. Only the q and v parameters are documented in the tool. There’s a link directing you to this page.

v

v

Displays the commandline interface version identification. This manual is valid for version 1.

AddRegistration

AddRegistration('bastb')
AddRegistration('bastb', true)
AddRegistration('bastb', false)
AddRegistration(User, 'bastb')
AddRegistration(User, 'bastb', true)
AddRegistration(User, 'bastb', false)
AddRegistration(CallCenter, 'callcenter')
AddRegistration(CallCenter, 'callcenter', true)
AddRegistration(CallCenter, 'callcenter', false)

The system is capable of monitoring multiple types of subscriptions, being User and CallCenter. User subscriptions allow you to process events related to an user and CallCenter subscriptions, well, you get the idea. The registration will target User entities if you leave it out.

The next parameter, bastb in the majority of the examples here, represents the loginname of the user being targeted. The loginname used in the examples here is not in the correct format and the XSI provider will return an error if you decide to use it. The correct format is <user>@<domain>, but you can go ahead and give it a try. You’ll find an error message in the logging produced by the backend. Your local XSI administrator will be able to get you a correct loginname. The system can monitor multiple accounts at once, so you’re not limited to 1.

The last parameter is optional and indicates the lifetime of the registration. Registrations are created with a keep-alive flag by default, meaning the system will do what it needs to keep receiving events related to this subscription. You can overrule this by specifying false, creating a temporary subscription that lasts for a maximum of one hour. Temporary subscriptions are not restarted when the connection to the XSI provider breaks.

The system will produce RegistrationMessages while monitoring users or callcenters. These messages are available through the Content (and TryContent) properties on the backend. More on that later on, in the Content paragraph.

The repository does not need to be started for you to create registrations. You can add them when the system has not been started. The system will activate them when the repository is started.

The console will display a json formatted string displaying the data stored in the object:

{"AddRegistration":{"RegType":0,"TargetLabel":"bastb","KeepAlive":true}}

Use JSONViewer (or any other JSON viewer) to apply user-friendly formatting to the message. You could use an online service, but you should be aware of the content you’re posting. Those messages may very well contain sensitive information which should not end up on the internet.

 RemoveRegistration

RemoveRegistration('bastb')
RemoveRegistration(User, 'bastb')
RemoveRegistration(CallCenter, 'cc_servicedesk')

Removes an existing subscription from the system. You can optionally specify the subscription domain – User or CallCenter, similar to AddRegistration.The default type of subscription is User.

The next parameter represents the name of the target object. There’s no real problem if the user has not been previously being added using AddRegistration: the system detects that the user is not being monitored. Messages are in the logging as well.

You’ll no longer receive call information regarding this target.

 Start

 Start()

Starts or restarts the backend. The system will create an HTTP connection to the XSI provider, if one doesn’t exist yet, and activate permanent registrations and newly added temporary registrations. Temporary added registrations are those added with the false option.

The system will do what needs to done to keep the HTTP connection active, meaning that the HTTP connection gets recreated when the repository decides that it’s required, to a certain extend. Here’s how it works:

• The system will abort immediately if this is the first attempt to build a connection. The idea here is that there’s probably a configuration problem, like an incorrect username and/or password, or an infrastructure problem.
• The system will stop connection attempts after 16 consecutive unsuccesfull attempts, using a 66 second delay between those attempts. You can specify another number.

Consuming applications can be informed of state changes through the RepositoryStatusChanged event.

Start may take little time to return. A little time should be considerably less than a second, but it’s not instant. It’s a good idea to follow the logging using a tool like logexpert.

Suspend

Suspend()

Suspends the system, by deactivating the active subscriptions and keeping the HTTP connection alive. The system will do what needs to be done to keep the connection alive.

Suspend is state independent; you can issue Suspend on a backend that’s currently suspended.

Temporary registrations – those that were added using the false option – are marked inactive and will not be restarted when the backend is restarted. The permanent subscriptions will however be restarted when the backend is restarted using Start().

Stop

Stop()

Stops the system by closing the HTTP connection and associated subscriptions. You can not reuse this backend and you’ll need to create a new instance.

Stop is state independent; you can issue Stop even when the backend has not been started yet.

Content

Content

Content returns the next available message from the queue. The system maintains the order the messages were received in to a certain degree.

The system will throw an InvalidOperationException when there are no messages on the queue. Issue MessageCount to get the number of messages stored or wait for the UpdateEvent mutex to change. Keep in mind that the repository may contain multiple messages.

Content is cached on the backend; there is no persistent storage. This means you’ll loose messages that have not been read from the queue if the application was to crash.

ActiveRegistrationCount

ActiveRegistrationCount

Returns the active registrations count. An active registration is a permanent or a temporary registration that has been added to the repository and has currently being activated.

MaintainedRegistrationCount

MaintainedRegistrationCount

Returns the number of maintained registrations. A maintained subscription is a Registration created using the true flag. The number of active registration may very well exceed the number of maintained registrations; in which case.

MessageCount

MessageCount

Returns the number of currently cached messages. This number increases as the backend recognizes messages and delivers them. The number decreases when a message is read from the queue using Content (or TryContent).

Events

The console is wired to a set of C# events, which will emit messages as the C# events are triggered. It’s expected behaviour when the console displays a message:

• … when the system recognizes a call.
  • UpdateEvent: Repository has a new message
• .. when the system is handled a registration request:
  • Registered: Attempt to add registration targeting bastb: OK
  • Registered: Attempt to add registration targeting bastb: Operation failed
  • Registered: Attempt to remove registration targeting bastb: OK
  • Registered: Attempt to remove registration targeting bastb: Operation failed
• Displays a message when the backend goes offline. And online:
  • RepositoryStatusChanged: Repository status is Online
  • RepositoryStatusChanged: Repository status is Offline

Things you need to know

Note that even though the source code of the XSI Repositoy Console is made available, you are not permitted to distribute the software. And I’m not responsible for damages caused by the product or parts of the product in any way, shape or form. You’re using the product at your own risk.

Want to use the backend and tooling? Contact me.