CIOC API User Guide Contents¶

Configuring Fields¶

The API results must include either Record Number or Name, and the link to the Details API for the given record. Many additional items can be added to the results through the setup for the View connected to the API Account.

The list of fields is configured through the Display Options of the API User Account’s View in the Search Results section (see image below - Community Information settings shown). The Show Options and Print Version settings do not apply to the API. To enable the Latitude and Longitude fields in the API, turn on the Map Search Results with Google Maps option. Best practice is for each API project to have its own View, which allows control over what the API sees without impacting other uses.

Access URL and Search Parameters¶

The main Search API is accessed through the following URLs (substituting your domain):

Community Information : Search

https://yoursite.cioc.ca/rpc/orgsearch.asp

Volunteer Opportunity : Search

https://yoursite.cioc.ca/rpc/oppsearch.asp

Volunteer Opportunity : Browse by Organization

https://yoursite.cioc.ca/rpc/browseoppbyorg

All Search API URLs accept a format parameter format=[xml|json]. If no format is specified, the default is JSON.

The Community Information and Volunteer Search API URLs support all search parameters available to the API account from the regular Search Results page from the UI (results.asp/bresults.asp in the UI), but at this time it does not include Saved Searches which are accessed through sresults.asp or some of the specialized Child Care search types accessed only through cresults.asp). The Volunteer Browse by Organization URL does not accept any additional search parameters, and always returns a list of organizations with active opportunities.

Which Parameters to Use?¶

There are hundreds of search parameters in the software, and which ones are available to the current user depend on various setup options. The best way to find the parameters available to the current user is by reviewing the Basic or Advanced Search forms.

Method 1: Execute a Search, Parse the URL

Execute any search that posts to results.asp or bresults.asp, and view the available parameters in the URL of the results page. This includes Basic and Advanced Search, all Taxonomy Searches, Volunteer Step-by-Step Search, and any search linked from the Record Details page.

Method 2: Copy the Form

You can directly copy HTML from the Basic or Advanced Search form and use it in another application.

Method 3: Turn on Search Parameter Key Display

The Basic and Advanced Search forms have a special settings to allow you to see what the search parameters would be as you type criteria into the form:

Available search forms with the Search Parameter Key Display:

• https://yoursite.cioc.ca/?SearchParameterKey=on
• https://yoursite.cioc.ca/advsrch.asp?SearchParameterKey=on
• https://yoursite.cioc.ca/volunteer/?SearchParameterKey=on
• https://yoursite.cioc.ca/volunteer/advsrch.asp?SearchParameterKey=on

Note

It is intentionally difficult to produce a complete list of records with no criteria. The Search API is not intended to be used for complete database downloads: use the CSV, Excel, or Sharing Format Export Feed for that purpose in the Community Information module. In the Volunteer Opportunities module, a complete list of current opportunities can be retrieved using the criteria DisplayStatus=C to retrieve all currently active opportunities.

Note

Get Clarity with Codes: Many fields that appear with numeric IDs when searching in the regular CIOC UI can be converted to use human-readable Codes instead. Using Codes provides clarity, predictability, and portability and is highly recommended. A search with ID in it (PBID, GHID, AIID, and so on...) can be converted to a Code search by changing ID to Code (PBCode, GHCode, AICode, and so on...). You can add/edit the codes for each item and display a list of available codes via the Setup Area for the given item. General Headings can be searched by Code as explained here, but also by Name - just change the GHType parameter to NM and the GHID parameter to GH.

Download the Schemas¶

The following schemas indicate what to expect when retrieving output in XML. If using a JSON format, the structure and contents are the same and the XSD serves as a reasonable guide. See the Sample JSON for more examples.

• Community Information: Search API Schema
• Volunteer Opportunity: Search API Schema
• Volunteer Opportunity: Browse by Organization API Schema

There are 3 pieces of information provided by default in the search results for the Search APIs:

• NUM/VNUM - The Record ID
• RECORD_DETAILS - A link to the record on the CIOC Site
• API_RECORD_DETAILS - A link to the API URL for the record

Other fields provided in the results correspond to the Search Results settings in the account’s View. A list of possible Field name values is available from the current CIOC Online Resources Field List.

Error Handling¶

JSON search results will be an object with a string error property. If there is an error of any kind, the error property will be a string value explaining the error. If there is no error, the error property will be null.

XML search results will have a <root> element containing an <error> element and a <recordset> element. If there is an error of any kind, the <error> element will contain a string value explaining the error and the <recordset> element will be a self-closed empty element. If there is no error, the <error> element will be a self-closed empty element, and the <recordset> element will contain a series of <record> elements (or if no records match the query, the <recordset> element will also be a self-closed empty element).

Sample XML¶

<root>
        <error/>
        <recordset>
                <record NUM="ABC00001">
                        <field name="RECORD_DETAILS">https://yoursite.cioc.ca/record/ABC00001</field>
                        <field name="API_RECORD_DETAILS">https://yoursite.cioc.ca/rpc/record/ABC00001?format=xml</field>
                        <field name="ORG_NAME">Organization Name</field>
                        <field name="LATITUDE">43.718193</field>
                        <field name="LONGITUDE">-79.722915</field>
                        <field name="LOCATED_IN_CM">Brampton (City of)</field>
                </record>
        </recordset>
</root>

<?xml version="1.0" encoding="utf-8"?>
<root>
        <error/>
        <recordset>
                <record VNUM="V-DEF0001" OPID="123">
                        <field name="RECORD_DETAILS">https://yoursite.cioc.ca/volunteer/record/V-DEF0001</field>
                        <field name="API_RECORD_DETAILS">http://tika-dev/rpc/opportunity/V-DEF0001?format=xml</field>
                        <field name="POSITION_TITLE">Position Title</field>
                        <field name="ORG_NAME">Organization Name</field>
                        <field name="COMM_BALLS">&lt;img src=&quot;https://yoursite.cioc.ca/images/teal_ball.gif&quot; alt=&quot;Community 1&quot; title=&quot;Community 1&quot;&gt;</field>
                        <field name="DUTIES">Description of Duties</field>
                        <field name="INTERESTS">Interest 1; Interest 2; Interest 3</field>
                </record>
        </recordset>
</root>

<?xml version="1.0" encoding="utf-8"?>
<root>
        <item>
                <ORG_NAME>Organization Name</ORG_NAME>
                <NUM>ABC00001</NUM>
                <OP_COUNT>4</OP_COUNT>
                <OPP_SEARCH_LINK>https://yoursite.cioc.ca/rpc/oppsearch.asp?NUM=ABC00001&amp;format=xml</OPP_SEARCH_LINK>
                <API_RECORD_DETAILS>https://yoursite.cioc.ca/rpc/record/ABC00001?format=xml</API_RECORD_DETAILS>
        </item>
</root>

Sample JSON¶

{
        "error":null,
        "recordset":[
                {
                "NUM":"ABC00001",
                "RECORD_DETAILS":"https://yoursite.cioc.ca/record/ABC00001",
                "API_RECORD_DETAILS":"https://yoursite.cioc.ca/record/ABC00001",
                "ORG_NAME":"Organization Name",
                "LATITUDE":43.718193,
                "LONGITUDE":-79.722915,
                "LOCATED_IN_CM":"Brampton (City of)"
           }
        ]
}

{
        "error":null,
        "recordset":[
                {
                "OPID":123,
                "VNUM":"V-DEF0001",
                "RECORD_DETAILS":"https://yoursite.cioc.ca/record/DEF0001",
                "API_RECORD_DETAILS":"https://yoursite.cioc.ca/record/DEF0001",
                "POSITION_TITLE":"Position Title",
                "ORG_NAME":"Organization Name",
                "COMM_BALLS": "<img src=\"https://yoursite.cioc.ca/images/teal_ball.gif\" alt=\"Community 1\" title=\"Community 1\">",
                "DUTIES":"Description of Duties",
                "INTERESTS":"Interest 1; Interest 2; Interest 3"
           }
        ]
}

[
        {
                "ORG_NAME": "Organization Name",
                "NUM": "ABC00001",
                "OP_COUNT": 4,
                "OPP_SEARCH_LINK": "http://yoursite.cioc.ca/rpc/oppsearch.asp?NUM=ABC00001",
                "API_RECORD_DETAILS": "http://tika-dev/rpc/record/ABC00001"
        }
]

Additional Feeds¶

Configuring Fields¶

The fields available in the Record Details API are identical to what is available when the API account is viewing the Record Details page through the regular UI. To change the fields available or their re-organize them, change the Field Groups and Details Fields setup of the View used by the API Account. Best practice is for each API project to have its own View, which allows control over what the API sees without impacting other uses.

Download the Schemas¶

The following schemas indicate what to expect when retrieving output in XML

• Community Information Details API Schema
• Volunteer Opportunity Details API Schema

If using a JSON format, the structure and contents are the same and the XSD serves as a reasonable guide.

Field Group name values are custom and determined by the View Setup. A list of possible Field name values is available from the current CIOC Online Resources Field List.

Error Handling¶

Any errors will be returned as HTTP errors. The only errors supported at this time are 404 (Not Found) and 401 (Permission Denied). 401 errors are provided with a textual reason if appropriate.

Sample JSON¶

Sample XML¶

Basic Conventions¶

All response messages can contain either a successful response or an error response. The error response can provide a message that will be displayed to the user indicating the source of the error.

Registration¶

The registration message is designed to simplify the configuration of a Resource Type in the Client Tracker system. While all configuration items can be entered by hand, the registration message ensures accuracy when setting complex URL settings.

The Client Tracker server initiates a request for registration data by performing a HTTP GET request to the Resource Type’s registration URL. The definition of the Registration response is defined in registration.xsd. The URL is stored with the other settings so that changes to the registration information can be fetched at the administrator’s request.

Resource Item Fetching¶

The Client Tracker allows the option of having a user fetch Resource Item details from the Resource Type by ID. At the user’s request the Client Tracker server performs an HTTP GET to the configured Fetch URL. The ID value entered by the user is substituted for any instance of [ID] in the Fetch URL. The definition of the Fetch response is defined in resourceinfo.xsd. The ID may be of any type that can be stored in 50 Unicode characters or less.

Resource Item Pushing¶

The Client Tracker also allows the Resource Type to push Resource Items into the user’s current Request. There are 3 pieces of information that the Client Tracker provides to the Resource Type that must be provided with every request to the Client Tracker:

1. The name of the user for which the request is being made
2. The remote key
3. The Client Tracker’s internal id for the Resource Type

These pieces of information are provided to the Resource Type for the current user through the Launch URL. When the user “Launches” a Resource Type, the Client Tracker opens a new browser window directed at the Launch URL where any instance of [CTID], [LOGIN] and [KEY] are replaced with the appropriate values to be provided in messages from the Resource Type. These values could be stored in the user’s session with the Resource Type.

The Resource Type can determine if the user is currently in a Request by making an HTTP POST request to https://clienttracker.cioc.ca/ct/rpc/is_in_request where the body of the POST is an isInRequest message as defined by incallrequest.xsd. The client tracker will respond with an isInRequest response message as defined in incallresponse.xsd. This response will include a list of Resource Item ids that have already been associated with the user’s current Request, if applicable.

The Resource Type can push a Resource Item into the user’s current Request by making an HTTP POST request to https://clienttracker.cioc.ca/ct/rpc/add_resource where the body of the POST is a pushResource message as defined in pushresource.xsd, with a response message as defined in pushresourceresponse.xsd.

Method 1: Using Forms Created Directly in the Client Tracker¶

With the method 1, the public user navigates with a browser to a URL as indicated above. No further programming is required; the software takes care of generating and processing the form. To use this method, it would be recommended to provide a simple link to the address https://clienttracker.cioc.ca/public/[AGENCY_CODE]/[CLASSIFICATION_CODE] with substitutions for your Agency Code and the Classification of Inquiry code, as described above.

Method 2 & 3: External Website Integration¶

In methods 2 and 3, a remote server makes a HTTP GET request to a URL as indicated above including an ApiKey query string parameter with a valid Public API Key (see next section). The remote server will be provided with a JSON response that includes the HTML rendered form contents (without form tag) and other relevant data as described below in the section covering JSON GET Responses.

In method 2 (partially-embedded in a remote site), the HTML form is configured to POST to the same URL as the GET request and the optional redirect_to query string parameter can be provided indicate a URL to which visitors will be redirected after their request has been successfully submitted. If no redirect_to query string parameter is provided, then the visitor will be redirected to a generic thank you message that can be viewed at https://clienttracker.cioc.ca/thanks.

In method 3 (fully-embedded in a remote site), the same URL used to to handle a GET request accepts a POST request with an application/x-www-form-urlencoded encoded body and returns a JSON encoded response as described in below in JSON POST Responses. As with the remote GET request, a valid ApiKey parameter is required. The ApiKey parameter may be provided as part of the query string or in the POST body.

{
        "alert": null,
        "form": "<!-- HTML Form Content -->",
        "errors: null
}

{
        "success": true
}

{
        "alert": "General Error Message",
        "form": "<!-- HTML Form Content -->",
        "errors: {
                "FieldName": "Specific Error",
                "FieldName2": "Other Specific Error"
        }
}