NIH | National Cancer Institute | NCI Wiki  

Contents of this Page

Additional Information

Introduction

The following details the use of a Process URL on an Alert Definition. This is the means employed to send Alert Reports to a software application. An Alert Definition may contain any combination and number of recipients for people and software. People are identified via email address and software applications via a standard http:// or https:// URL.

It is assumed the reader already has some experience with the Sentinel Tool UI and Alert Reports. The Sentinel Online Help provides additional information not repeated here.

Enter the Process URL

  • To add a Process URL as a recipient, from the Report Details tab of the Alert Definition Edit page, enter the URL in the text field labeled "Additional email address or Process URL" and select Add. The URL will appear in the Recipients list.
  • To remove the URL, select the entry in the Recipient's list and select Remove.
  • Editing a URL is done by adding a new URL and removing an old one.

URL format

The URL must be complete and in standard format. If embedded spaces are needed use the "%20" character sequence, e.g. [http://my.domain.com/my%20application]. Application variables may be specified using "?" and the variable names and values, e.g. [http://my.domain.com/my%20application?var1=value1&var2=value2].

Variable "alertreport"

When an Alert Report is created and sent to a software application, the URL supplied in the recipient list is suffixed with "alertreport=<report name>.xml" (no quotes). If "?" already appears in the recipient URL, the variable is prefixed with an ampersand, "&", otherwise a question mark, "?". The "alertreport" value is always a fully qualified XML URL, e.g. [http://cadsrsentinel.nci.nih.gov/AlertReports/Check_Test_20080129044210561.xml]. See below for more on the XML content.

Recipient Process Requirements

The receiving software application must adhere to the following requirements when used as an Alert Report recipient.

  1. The recipient is notified via a GET request to the URL with the "alertreport" variable included as noted above.
  2. The recipient must acknowledge the request by setting the HTTP return code to 200. All other values indicate an error.
  3. The recipient must not process the XML message at the time of notification. The notification makes the recipient aware the XML message exists and it may be retrieved at any time using a simple HTTP GET after the notficiation is acknowledged.
  4. The recipient must process the special value "alertreport=http://identity", e.g. http://cadsrsentinel-stage.nci.nih.gov/cadsrsentinel/do/urltest?alertreport=http://identity. The response message must identify the geographic location, contact administrator, software application name, version, etc, for the software application and the server which hosts it.

Periodic audits are performed on all URL recipients. Applications failing to respond to "identity" will be followed with an email and/or phone call to the Alert Definition Creator. Failing a reply from the Creator the URL recipient is removed from the Alert Definition.

XML

The XML created for a Process Recipient URL is defined by a DTD. The content and detailed documentation follow. The XML structure is shown with comments following each element. The hierarchical tree of elements is:

  • cadsr
    • alertReport
      • database
      • definition
        • name
        • id
        • intro
        • createdBy
        • recipient
        • summary
        • lastAutoRun
        • frequency
        • status
        • level
        • start
        • end
        • createdOn
      • changedItem
        • details
          • change
      • associateItem
      • group
        • associate

DTD Elements and Attributes

Following are the details for the Alert Report elements and attributes.

  • All dates are formatted "YYYY-MM-DD" and times are formatted "YYYY-MM-DD HH:MI:SS.TTT", where YYYY is the year, MM is the month, DD is the day, HH is the hour, MI is the minutes, SS is the seconds and TTT is thousands of a second. This follows the java.sql.Timestamp formatting.
  • Attributes noted as "may be empty" will apprear in the XML as attribute="".

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE cadsr SYSTEM "http://cadsrsentinel.nci.nih.gov/dtd/cadsrsentinel-1.0.dtd">

Header for all Alert Report XML files.

<cadsr> ... </cadsr>

The file root element.

  • Required
  • Must have an end tag
  • Appears once in the XML file
  • Contains a message from/to the caDSR.

<alertReport softwareName="NCI caDSR Sentinel Report Generator" softwareVersion="..." version="1.0"> ... </alertReport>

Describes the results of the Alert Report generation. Content is identical to the HTML generated although the form and organization is different.

  • Child of element <cadsr>
  • Required
  • Must have an end tag
  • Appears once
  • Attributes
    • softwareName - the name of the software which produced the XML message.
    • softwareVersion - the version of the software which produced the XML message.
    • version - the DTD schema version of the XML message.

<database server="..." name="..." rai="..." />

Identifies the caDSR database from which the data is interrogated.

  • Child of element <alertReport>
  • Required
  • No end tag
  • Appears once
  • Attributes
    • server - the name of the database server, this may be empty for security
    • name - the human readable database name
    • rai - the Registration Authority Identifier for the database

<definition> ... </definition>

Details the Alert Definition attributes.

  • Child of element <alertReport>
  • Required
  • Must have an end tag
  • Appears once
  • No attributes

<name value="..." />

Provides the Alert Definition Name

  • Child of <definition>
  • Required
  • No end tag
  • Appears once
  • Attributes
    • value - the name of the Alert Definition

<id> ... </id>

Provides the Alert Definition unique database id.

  • Child of <definition>
  • Required
  • Must have an end tag
  • Appears once
  • Contains the database unique identifier for the Alert Definition

<intro> ... </intro>

Provides the user defined introduction appearing on the Alert Report.

  • Child of <definition>
  • Required
  • Must have an end tag
  • Appears once
  • Contains the text used as the Introduction appearing at the top of the HTML Alert Report

<createdBy user="..." name="..." email="..." />

Provides the Creator contact information.

  • Child of <definition>
  • Required
  • No end tag
  • Appears once
  • Attributes
    • user - the database user id for the Alert Definition Creator, can not be empty
    • name - the user name, may be empty
    • email - the user email address, may be empty

<recipient user="..." name="..." email="..." />

Provides the recipients contact information.

  • Child of <definition>
  • Required
  • No end tag
  • Appears once for each Alert Report recipient, including Process URLs
  • Attributes
    • user - the database user id for the Alert Definition Creator
    • name - the user name only if the email address is not null or empty
    • email - the user email address, may be empty

<summary> ... </summary>

Provides the Alert Definition Criteria and Monitors summary as free form text.

  • Child of <definition>
  • Required
  • Must have an end tag
  • Appears once
  • Contains the descriptive Alert Definition summary text which also appears on the Edit page of the UI and within the HTML Alert Report

<lastAutoRun time="..." />

Provides the last Alert Report automatic nightly generation for the Alert Definition.

  • Child of <definition>
  • Required
  • No end tag
  • Appears once
  • Attributes
    • time - the time last processed by the nightly Auto Report Creation

<frequency unit="..." />

Provides the frequency setting to analyze the Alert Definition for report generation.

  • Child of <definition>
  • Required
  • No end tag
  • Attributes
    • unit - either "Day", "Week" or "Month"
    • value - depends on the setting for unit.
      • "Day" - ignored
      • "Week" - the day of the week when, 0 = Sunday
      • "Month" - the day of the month

<status code="..." />

Provides the Alert Definition defined status.

  • Child of <definition>
  • Required
  • No end tag
  • Attributes
    • code - the status code selected on the Edit page for the Alert Definition, "Active", "Inactive", "Once", "Range"
    • beginDate - when code is "Range", this contains the begin date of the range, it may be empty
    • endDate - when code is "Range", this contains the end date of the range, it may be empty

<level depth="..." />

Provides the hierarchical level limit for the reported Associated Item groups.

  • Child of <definition>
  • Required
  • No end tag
  • Attributes
    • depth = the level number entered on the Edit Report Details tab for the Alert Definition

<start date="..." />

Provides the report activity start date.

  • Child of <definition>
  • Required
  • No end tag
  • Attributes
    • date - the report starting date, same rules apply as the Run page "Start Date" on the Sentinel Tool

<end date="..." />

Provides the report activity end date.

  • Child of <definition>
  • Required
  • No end tag
  • Attributes
    • date - the report ending date, same rules apply as the Run page "End Date" on the Sentinel Tool

<createdOn time="..." />

Provides the time the report output was collected and assembled for the XML and HTML output.

  • Child of <definition>
  • Required
  • No end tag
  • Attributes
    • time - the date and time this message was created

<changedItem type="..." name="..." id="..." publicId="..." version="..." modifiedByUser="..." modifiedByName="..." modifiedTime="..." createdByUser="..." createdByName="..." createdTime="..." changeNote="..."> ... </changedItem>

Identifes the Administered Item changed during the report activity period, see <start> and <end> above.

  • Child of element <alertReport>
  • Optional
  • Must have an end tag
  • Attributes
    • type - the Administered Item type per the following table

Type

Description

Type

Description

Type

Description

cd

Conceptual Domain

con

Concept

conte

Context

cs

Classification Scheme

csi

Classification Scheme Item

de

Data Element

dec

Data Element Concept

oc

Object Class

prop

Property

proto

Protocol

pv

Permissible Value

qc

Form/Template

qcm

Form Module

qcq

Form Question

qcv

Form Valid Value

vd

Value Domain

vm

Value Meaning

 

    • name - the item Long Lame
    • id - the item unique database id
    • publicId - the item Public ID
    • version - the item Version Number exactly as it appears in the caDSR database, i.e. decimal fractions ".0" may appear as simple integers with no decimal
    • modifiedByUser - the database User ID for the person who last changed the item at the time the report is created
    • modifiedByName - the name of the modifiedByUser
    • modifiedTime - the time of the last change
    • createdByUser - the database User ID for the person who created the item
    • createdByName - the name of the modifiedByUser
    • createdTime - the time of creation
    • changeNote - the text entered by the Curator to annotate the reason for the change |

      <details modifiedByUser="..." modifiedByName="..." time="..."> ... </details>

      Contains the activity for the Administered Item marked with the same user and time stamp.

  • Child of element <changedItem>
  • Optional
  • Must have an end tag
  • Attributes
    • modifiedByUser - the database User ID for the person who made the changes detailed within this tag
    • modifiedByName - the name of the modifiedByUser
    • time - the time of the change |

      <change attribute="..." oldValue="..." newValue="..." />

      Itemizes a single Administered Item attribute value change.

  • Child of element <details>
  • Optional
  • No end tag
  • Attributes
    • attribute - the item attribute value being changed. Permissible values follow, all attributes with the "IDSEQ" suffix have an oldValue and/or newValue in the format _[caCORE:name] ([caCORE:public id]v[caCORE:version]). This is consistent with the appearance on the HTML report output.

Attribute

Description

Attribute

Description

ASL_NAME

Workflow Status

BEGIN_DATE

Begin Date

C_DE_IDSEQ

Child DE

C_DEC_IDSEQ

Child DEC

C_VD_IDSEQ

Child VD

CD_IDSEQ

Conceptual Domain

CDE_ID

Public ID

CDR_IDSEQ

Complex DE

CHANGE_NOTE

Change Note

CON_IDSEQ

Concept Class

CONCAT_CHAR

Concatenation Character

CONDR_IDSEQ

Concept Class

CONTE_IDSEQ

Owned By Context

CONTE_IDSEQ

Designation Context

CREATED_BY

Created By

CRTL_NAME

Complex Type

CS_CSI_IDSEQ

Classification Scheme Item

CS_ID

Public ID

CSTL_NAME

Category

DATE_CREATED

Created Date

DATE_MODIFIED

Modified Date

DCTL_NAME

Document Type

DE_IDSEQ

Data Element

DE_REC_IDSEQ

DE_REC_IDSEQ

DEC_ID

Public ID

DEC_IDSEQ

Data Element Concept

DEC_REC_IDSEQ

DEC_REC_IDSEQ

DECIMAL_PLACE

Number of Decimal Places

DEFINITION_SOURCE

Definition Source

DELETED_IND

Deleted Indicator

DESCRIPTION

Description

DESIG_IDSEQ

Designation

DETL_NAME

Designation Type

DISPLAY_ORDER

Display Order

DISPLAY_ORDER

Document Display Order

DOC_TEXT

Document Text

DTL_NAME

Data Type

END_DATE

End Date

FORML_NAME

Data Format

HIGH_VALUE_NUM

Maximum Value

LABEL_TYPE_FLAG

Label Type

LAE_NAME

Language

LAE_NAME

Designation Language

LATEST_VERSION_IND

Latest Version Indicator

LONG_NAME

Long Name

LOW_VALUE_NUM

Minimum Value

MAX_LENGTH_NUM

Maximum Length

METHODS

Methods

MIN_LENGTH_NUM

Minimum Length

MODIFIED_BY

Modified By

NAME

Name

OBJ_CLASS_QUALIFIER

Object Class Qualifier

OC_ID

Public ID

OC_IDSEQ

Object Class

OCL_NAME

Object Class Name

ORIGIN

Origin

P_DE_IDSEQ

Parent DE

P_DEC_IDSEQ

Parent DEC

P_VD_IDSEQ

Parent VD

PREFERRED_DEFINITION

Preferred Definition

PREFERRED_NAME

Preferred Name

PROP_ID

Public ID

PROP_IDSEQ

Property

PROPERTY_QUALIFIER

Property Qualifier

PROPL_NAME

Property Name

PV_IDSEQ

Permissible Value

QUALIFIER_NAME

Qualifier

QUESTION

Question

RD_IDSEQ

Reference Document

RDTL_NAME

Document Text Type

REP_IDSEQ

Representation

RL_NAME

Relationship Name

RULE

Rule

SHORT_MEANING

Meaning

UOML_NAME

Unit Of Measure

URL

URL

URL

Document URL

VALUE

Value

VD_ID

Public ID

VD_IDSEQ

Value Domain

VD_REC_IDSEQ

VD_REC_IDSEQ

VD_TYPE_FLAG

Enumerated/Non-enumerated

VERSION

Version

 

 

 

    • oldValue - the value prior to the change, may be empty
    • newValue - the value after the change, may be empty |

      <associateItem type="..." name="..." id="..." publicId="..." version="..." modifiedByUser="..." modifiedByName="..." modifiedTime="..." createdByUser="..." createdByName="..." createdTime="..." changeNote="..."> ... </associateItem>

      Identifies items directly and indirectly associated to the changed Administered Item.

  • Child of element <alertReport>
  • Optional
  • Must have an end tag
  • Attributes
    • type - see <changedItem> above
    • name - see <changedItem> above
    • id - see <changedItem> above
    • publicId - see <changedItem> above
    • version - see <changedItem> above
    • modifiedByUser - see <changedItem> above
    • modifiedByName - see <changedItem> above
    • modifiedTime - see <changedItem> above
    • createdByUser - see <changedItem> above
    • createdByName - see <changedItem> above
    • createdTime - see <changedItem> above
    • changeNote - see <changedItem> above |

      <group changedItemId="..."> ... </group>

      Provides the item associations to form the groups reported in the HTML.

  • Child of element <alertReport>
  • Optional
  • Must have an end tag
  • May appear 0 or more times
  • Attributes
    • changedItemId - the id attribute from the <changedItem> element to which this group applies |

      <associate childItemId="..." parentItemId="..." />

      Provides a single association between the <changedItem> and <associateItem> or between an <associateItem> and <associateItem>. For every <associateItem> associated to the <changedItem> the parentItemId attribute for this element will be the same as the changedItemId on the containing <group> element.

  • Child of element <group>
  • Required
  • No end tag
  • Will appear 1 or more times
  • Attributes
    • childItemId - the id attribute from the <changedItem> or <associateItem> element to which to associate the parent item
    • parentItemId - the id attribute from the <changedItem> or <associateItem> element which is considered hierarchically a parent to the item identified by the childItemId |

 

 

  • No labels