Xml alert

This document describes the XML Alert webservice of the Carerix suite of application editions

Updated over a week ago

Introduction

This interface provides an API which returns the number of unread e-mails and all pending meeting objects in an XML format. This information can be used to tell the user about incoming mails or upcoming meetings, and even to jump to the e-mail overview or to a specific meeting in Carerix.

XML format

The XML representation of the Carerix alert information has the format described below.

<?xml version="1.0" encoding="UTF-8"?>

<alert>
<emails>
<email id="[id]">
<received>[received]</received>
<formatted>[received formatted for application]</formatted>
<subject>[subject]</subject>
<from>[from]</from>
</email>
...
</emails>
<meetings>
<meeting id="[id]">
<deadline>[deadline]</deadline>
<formatted>[deadline formatted for application]</formatted>
<subject>[subject]</subject>
</meeting>
...
</meetings>
</alert>

If there are no unread e-mails, the e-mails part is empty. If there are no upcoming meetings to be warned about, the meetings-part is empty.

For example there are 2 unread e-mails and one upcoming meeting, then the XML looks like this:

<?xml version="1.0" encoding="UTF-8"?>

<alert>
<emails>
<email id="10321">
<received>2007-08-30 13:15:08</received>
<formatted>30-08-2007 13:15</formatted>
<subject><![CDATA[Request for information]]></subject>
<from><![CDATA["Peter White" <p.white@business.com>]]</from>
</email>
<email id="10345">
<received>2007-08-30 13:25:11</received>
<formatted>30-08-2007 13:25</formatted>
<subject><![CDATA[Re: Meeting on Friday]]></subject>
<from><![CDATA["Angela (Brainwire)" <angela@brainwire.com>]]</from>
</email>
</emails>
<meetings>
<meeting id="10298">
<deadline>2007-08-30 14:00:00</deadline>
<formatted>30-08-2007 14:00</formatted>
<subject><![CDATA[Afternoon meeting with design team]]></subject>
</meeting>
</meetings>
</alert>

Query operation

Use a HTTP (or HTTPS) GET request with the following URL to retrieve the XML document with alert information:

http://res.carerix.com/cgi-bin/WebObjects/[AppName].woa/wa/Ajax/xmlAlert?user=[UserID]&pwd=[xmlAlertPassword]

Argument NameRequiredDescriptionuser Yes Scrambled UserID of a Carerix user pwd No Alternative way of providing the xmlAlertPassword (see security) 

Notes

  • AppName - To find your application name: in the Carerix application, look at the properties of any page (right-click and select properties), you will find the application name in the URL of the page.

  • UserID - The scrambled userID is only available through a template in which the scrambled userID is calculated.

  • xmlAlertPassword - To find this password: in the Carerix application, go to the XML section in the Settings module and copy the xmlAlertPassword value.

Create URL using CxScript

To automatically create the correct URL for the query use the following CxCript code in a template (select the Templates module in your Carerix system):

<cx:bare-string-format>
<cx:if condition="$request.isSecure = 1">https://</cx:if>
<cx:if condition="$request.isSecure = 1" not="">http://</cx:if>
<cx:write value="$request.fullHostName"/>/cgi-bin/WebObjects/
<cx:write value="$utilities.userDefaults.Customer" />Web.woa/wa/Ajax/xmlAlert?user=
<cx:write value="$activity.owner.scrambledUserID" />&pwd=
<cx:write value="$settings.xmlapi.xmlAlertPassword" />
</cx:bare-string-format>

Previous code will result in an URL like: http://res.carerix.com/cgi-bin/WebObjects/PublicTest.woa/wa/Ajax/xmlAlert

The argument values in the URL are retrieved using the following CxScript code:

  • UserID - <cx:write value="$activity.owner.scrambledUserID"/>

  • xmlAlertPassword - <cx:write value="$settings.xmlapi.xmlAlertPassword"/>

Remarks

  • Combining previous code in a template will create the personal URL for every application user.

  • If the userID is not provided, or no user with that userID exists, an empty XML-document (only the header) is returned.

Security !

Do not supply the pwd argument as an URL parameter, this is enabled for testing purposes only. Instead, include the password in the x-cx-pwd header. This password is an arbitrary string which is set by administrative users of the Carerix application in the module Settings, xmlAlertPassword. If no password is set, or the password is empty, the XML alert will be disabled.

Carerix Jump

To immediately 'jump' to an e-mail or meeting in the Carerix application use 1 of the following URL's:

  • If your application address starts with <AppName>.carerix.net use http://[AppName].carerix.net/jump.html?page=[PageName]&id=[ID]

Argument NameRequiredDescriptionurl No Address of the application to jump to (like publictest.carerix.com). Necessary for carerix.com, allowed (not necessary) for carerix.net. page No Name of the page to jump to. If empty or not provided, the default page (e-mail overview) is shown id No ID of the object in case page is a detail page PageName valuesDescriptionEditToDoPage Detail page for e-mail or meeting 

Examples

http://res.carerix.com/jump.html?url=publictest.carerix.com&page=EditToDoPage&id=1234
http://publictest.carerix.net/jump.html?page=EditToDoPage&id=1234

Notes

  • The URL takes the user to the application login page. If auto logon is activated, the user immediately sees the detail page with the e-mail or meeting. If autologon wasn't activated for the computer the user first needs to supply login credentials before seeing the e-mail or meeting.

  • If the supplied id for the e-mail or meeting does not exist, or if the user is not allowed to view the e-mail or meeting, the default Carerix application page (the e-mail overview) is shown.

Create the URL using CxSCript

To retrieve the first part of the jump URL use the following CxScript code:

<cx:bare-string-format>
<cx:let name="net" value="$request.fullHostName" invoke="containsString:" arg0=".carerix.net">
<cx:if condition="$request.isSecure = 1">https://</cx:if>
<cx:if condition="$request.isSecure = 1" not="">http://</cx:if>
<cx:write value="$request.fullHostName"/>/jump.html?
<cx:if condition="$net = 1" not="">url=
<cx:write value="$utilities.userDefaults.Customer" invoke="lowercaseString"/>.carerix.com&
</cx:if>
</cx:let>
</cx:bare-string-format>

Previous code will result in an URL like: http://publictest.carerix.net/jump.html

Notes

  • Combine the result of previous code with the parameters page=[PageName] and id=[ID] to compile the complete URL.

  • The generated URL will automatically be in the correct domain (.net or .com).

Did this answer your question?