Harmony API developers documentation (version 2.2)
-
Upload
harmony-the-1-cloud-application-development-run-time-platform -
Category
Technology
-
view
529 -
download
2
description
Transcript of Harmony API developers documentation (version 2.2)
Harmony API
Developers documentation
Version 2.2
Overview
• Harmony exposes all its functionality as a set of web services.
• JSON is the format of the messages, HTTPS is the transport.
• Basic authentication is used to authenticate all API calls or a token provided when user has previously logged in.
• All web services have a single end-point:– https://<domainname>/handler.yaws - when used with
security token– https://<domainname>/ws/handler.yaws – when used
with basic authentication
Message and response format
• An API call consists of URL parameters. These parameters can be simple strings or JSON formatted structures
• A response of an API call is always returned as JSON object. If it contains “exception” property, the call was unsuccessful. The lack of exception property signifies the success of the API call.
Exceptions• The returned JSON object contains the exception property {exception,
<exception_type>} and possibly some other information• Here is a list of the exceptions Harmony can return:
– not_authenticated : user is not authenticated to make this call– not_authorized: user is not authorized to perform the specified
action– dialog_already_submitted – has also dialog_id and key– dialog_withdrawn– has also dialog_id and key– search_query_invalid– key_not_found– dialog_name_not_found– harmony_down – Harmony is not responding– improper_event_format– no_facts_or_ref_objects– no_event_name– event_not_found– unkown_facts
Required parameters
• message - determines the operation of the web service to be executed; should appear in every API call
• token - security token – not needed for all messages; only required when using “token” authentication; not required when using basic authentication.
Types of messages
• Based on the authentication state of the user– (0) When no configuration is uploaded– (1) When user is not authenticated– (2) When config is uploaded and user is
authenticated– (3) If user is member of the Admin group
0. No config API calls
• When no configuration is uploaded, only these 3 calls are allowed:– get_all_lucidchart_diagrams– get_lucidchart_diagram– create_empty_config
• For all other API calls, Harmony would return {exception, no_config}
• If configuration is present but still one of these three calls are performed, Harmony will return no_token, not_authenticated or config_present exception depending whether the user is already authenticated or not.
No config API calls
get_all_lucidchart_diagrams
• Description: This call will ask Harmony to start a OAuth communication with LucidChart.com for retrieving the user’s diagrams.
• Input parameters:– No additional parameters other than the default
“message”• Response: The URL to redirect the browser
to. This is the OAuth page of LicidChart.com Web service where the user should enter the credentials.
get_all_lucidchart_diagrams
get_lucidchart_diagram
• Description: This call will ask Harmony to start a OAuth communication with LucidChart.com for retrieving a specific user diagram. If successful, the diagram will be converted to Harmony’s configuration. Then Harmony will start a OAuth communication with Google. After receiving permission, a new spreadsheet document with the same name as the diagram will be generated in the user’s Google account. The configuration will be uploaded to Harmony and will populate the spreadsheet.
• Input parameters:– diagram_id – the LucidChart.com identification of the diagram.
• Response: The URL to redirect the browser to. This is the OAuth page of LicidChart.com Web service where the user should enter the credentials.
get_lucidchart_diagram
create_empty_config
• Description: With this API call, Harmony will start a OAuth communication with Google. After receiving permission, a new spreadsheet document with the supplied name will be generated in the user’s Google account. The configuration will be uploaded to Harmony. This configuration contains an example dialog “test dialog” and an example rule.
• Input parameters:– config_name – the name of the Google spreadsheet that
will be created.• Response: The URL to redirect the browser to. This is
the OAuth page of Google documents .Web service where the user should enter the credentials.
create_empty_config
1. Not authenticated API calls
• Two calls are allowed when (a) user is not authenticated, but (b) there is a configuration uploaded:– get_public_token– login
• All other calls will fail with {exception, not_authenticated} or {exception, no_token}
get_public_token
• Description: This call will try to get a public token for accessing the public resources Harmony provides. This is usually done on page load. Note that if there are no public resources, Harmony will return {exception, not_authenticated}.
• Input parameters:– No additional parameters required.
• Response: JSON object, containing:– token – the newly generated public token
get_public_token
login• Description: Sent when user tries to authenticate. Harmony supports four
forms of authentication: through OpenID (for Yahoo!, Aol or any other OpenID provider); through Facebook’s connect protocol; through OAuth for authentication with Twitter, Google and LinkedIn; and through the LDAP protocol.
• Input parameters– method– a predefined set of allowed methods:
• google• facebook• yahoo• aol• twitter• linkedin• opened
– url – specifies the url of the OpenID provider
• ldap– user– password
– request_page – the encoded URL of the page the user was on and where Harmony will redirect after successful login
• Response: For LDAP authentication, the token is returned. Otherwise, the user is redirected to the appropriate authentication page. Then the user is returned to “request_page” and the token is embedded in the URL as param.
login
2. User authenticated API calls
• These API calls expect a token param to be present. If no token is provided, {exception, no_token} is returned without further attempt to check the API call.
logout
• Description: Sent with request to logout the currently logged in user. The user’s token will be invalidated.
• Input parameters: Default parameters only
• Result: the token will be invalidated
logout
get_dialog_names
• Description: Retrieves the list of business events. They are all represented as dialogs. The result is an array of business event names. The name can then be used to retrieve the event definition for example. Can also contain the dialog title – what should be presented to the end user. Read-only operation.
• Input parameters: Default parameters only.• Response: JSON array “dialog_names” containing JSON
objects with properties:– name – this should be used in further API calls to identify this
particular dialog– title – a title to display to the user (might be missing). It is
language dependent.• Possible exceptions: not_authenticated
get_dialog_names
get_work_items
• Description: Retrieves all outstanding work items (dialogs) from all work queues. Read-only operation.
• Input parameters: Default parameters only.• Response: JSON array “work_items” containing JSON objects with
properties:– case_id - the Case ID to which each work items belongs to;– dialog_id - each dialog instance has a unique identifier;– dialog_name - matches one of the business event names retrieved with
a get_dialog_names call;– queue - the work queue name, can be either a user or a group work
queue;– index - information from the case is indexed and displayed for
reference, in the example it is the relatie name;– dialog_title – optional, the title of the dialog that should be displayed
to the user• Possible exceptions: not_authenticated, not_authorized
get_work_items
get_case_ids
• Description: Requests the case ids of all the cases. Used when there is an item of type “case_id” so to fill the select with the returned keys. Read only operation.
• Input parameters: Default parameters only• Result: JSON array “case_ids” containing
strings.• Possible exceptions: not_authenticated
get_case_ids
submit_dialog
• Description: Once all values in a dialog are filled-in by the user, the dialog is submitted to Harmony. Harmony will then execute all business rules related and will enrich the case data for the case. This is an operation that changes data and state. Write only operation.
• Input parameters– Default parameters– payload - contains the message payload, in this case, the contents of the dialog to
be submitted to Harmony• dialog_name• dialog_id• case_id• facts
– concept– attrib– value
• Result: {success: true} or exception• Possible exceptions: not_authenticated, not_authorized,
improper_event_format, no_facts_or_ref_objects, no_event_name, event_not_found, unkown_facts, dialog_withdrawn, dialog_already_submitted
submit_dialog
submit_for_predictions
• Description: Used to send data the moment the user enters it so to show prediction from the firing of rules. Write only operation.
• Input parameters:– Default parameters;– payload – in the same format as with
submit_event• Result: {success: true} or exception• Possible exceptions:– same as submit_event call
submit_for_predictions
get_predictions
• Description: After a “submit_for_predictions” call, get_predictions is sent to collect the outcome of the predict data. Read only operation.
• Input parameters:– Default parameters– case_id – identifies the case we want to get prediction
for• Result: JSON object
– case_id – identifies the case the data belongs to– facts – JSON array of facts – see Facts array slide
• Possible exceptions: not_authenticated, not_authorized
get_predictions
get_dialog
• Description: Retrieves the definition of the business event, as well as all the related case data for it . Read-only operation.
• Input parameters:– Default parameters– name - the name of the event, from a call to get_dialog_names.– case_id – (optional) the case id, as retrieved with a call to get_work_items. If it is not present, only the
dialog definition will be retrieved without any preloaded data.– dialog_id – (optional) needed for retrieving outstanding work item (together with case_id)
• Response: JSON object:– name – the name of the dialog– contents – JSON array of dialog items
- concept – first part of the name of the dialog item- attrib – second part of the name of the dialog item- type - the dialog item type;- ext - in case the type is multiple_choice, the variable contains the list of possible options;- value - "undefined" means that the values is still not set for this case;- can_override - if "yes", the item can be overridden by the user (by default once a pair has a value, it is disabled and
cannot be changed);- lookup – whether the item is a key of a reference data- lookup_source – where to look for the corresponding reference date- required – whether this dialog item is required to be filled in;- initial_state – whether the item should be initially hidden- description – a description of the item, presented instead of the c/a pair
• Possible exceptions: not_authenticated, not_authorized, dialog_withdrawn, dialog_already_submitted, dialog_name_not_found, key_not_found
get_dialog
get_case_data
• Description: Retrieves all case data for the case. Read-only operation. Note that it returns a list because all children will be returned in separate objects.
• Input parameters– Default parameters– case_id - determines the case for which case data will be
retrieved;• Response: JSON array of JSON objects containing:
– case_id - determines the case for which case data is retrieved
– facts – JSON array – see Facts array slide• Possible exceptions: not_authenticated,
not_authorized, key_not_found
get_case_data
get_case_history
• Description: Retrieves history for a specific case. Read only operation.• Input parameters:
– Default parameters– case_id – identifies the case we want to get history for
• Result: the JSON object “case_history” containing JSON array of JSON objects with properties:– case_id – case identifier– dialog_id – internal event reference number– dialog_name – the name of the dialog– queue – who must handle the dialog (or already did)– because – reason why the dialog was asserted. this is an object. same as in
fact object– asserted_on – (optional) when the dialog was asserted– done_on – (optional) when the dialog was submitted– who – (optional) – submitted by who
• Possible exceptions: not_authenticated, not_authorized
get_case_history
get_facts_for_history_record
• Description: Retrieves the facts that where submitted with a specific dialog. Read only operation.
• Input parameters:– Default parameters– case_id – identifies the case – dialog_id – identifies the dialog that submitted the facts
• Result: the JSON object “facts” containing JSON array of JSON objects with properties same as described in Facts array slide
• Possible exceptions: not_authenticated, not_authorized
get_facts_for_history_record
search
• Description: Searches for criteria in the submitted data. Read only operation.
• Input parameters:– Default parameters– criteria – the search criteria
• Result: JSON object:– criteria – the search criteria– hits – how many results we have in the array– time_it_took – the milliseconds needed for lucene to find the data– results – JSON array of JSON objects:
• case_id – identifies the hit is for which case• text – the text that contains the hit• score – lucene score of how close the match is to the creteria
• Possible exceptions: not_authenticated
search
get_meta_info
• Description: Gets information for the currently logged in user and the uploaded configuration. Read only operation.
• Input parameters: Default parameters only• Result JSON object:
– name – as defined in Excel configuration– username – as defined in Excel configuration– email – as defined in Excel configuration– groups – the groups the user belongs to
• Possible exceptions: not_authenticated
get_meta_info
test_predictions
• Description: submits facts to Harmony and gets the predictions (outcomes) of the fired rules. The original facts are also returned, e.g. the whole case data.
• Input parameters:– facts: JSON array containing fact objects. same as
get_predictions• Result JSON object: same as the result from
get_predictions. Note that case_id will be equal to “test_outcome” for every call.
• Possible exceptions: not_authenticated
test_predictions
get_reference_data
• Description: searches for “term” in the reference data, specified in “concept” and “attrib”. The results are returned and should be shown to the user to choose from them.
• Input parameters:– concept – the concept of the reference key item for which we perform the search. This
corresponds to the name of the reference object– attrib – the attribute of the reference key item for which we perform the search. This
corresponds to the name of the reference key.– case_id – context param – the case id of the current case– dialog_id – context param – the dialog id of the current dialog (on which the dialog item
(reference key) is present)– dialog_name – context param – the name of the current dialog (on which the dialog item
(reference key) is present)– term – the search term
• Result JSON object “reference_data” with the following properties:– object – the name of the reference object. the same as “concept” param– keys – an array of the matches reference keys
• name – the name of the reference key. same for each result. same as “attrib” param• value• attributes – an array of reference attributes corresponding to this reference key
– name– value
• Possible exceptions: not_authenticated
get_reference_data
get_correlation_data
• Description: this API call tries to find a case that contains the “term” in a “concept” / “attrib” pair. This way we can switch the case we are working on.
• Input parameters: same as in get_reference_data• Result JSON object “correlation_data” with the following:
– typed_key – an object, represents the dialog item the user typed in• concept• attrib• value
– additional_parts – an array of objects of form typed_key if the correlation_key is made of multiple parts
– filled_items – an array, dialog items that have values in the case we are switching to• concept• attrib• value
– case_id – the case id we have to switch context to• Possible exceptions: not_authenticated
get_correlation_data
Facts array of JSON objects
• Returned by get_predictions.• Each element contains the following properties:
– concept– attrib– value– queue (optional)– because (optional)
• concept• attrib• op• value
– is_ref
3. Admin user API calls
• If user is authenticated and is member of the Admin group, the following API calls are allowed to be performed.– flush– get_config– get_version– get_reference_objects_names– get_reference_object– ref_attrib_update– ref_key_update
• If these calls are tried from a user who doesn’t belong to the Admin group, Harmony will return {exception, not_authorized}
flush
• Description: Flushes the loaded configuration.
• Input parameters: only the default ones
• Result: {success, true} or exception• Possible exceptions:
not_authenticated, not_authorized
flush
get_config
• Description: Returns XML representation of the uploaded configuration.
• Input parameters: only the default ones
• Result: XML of the configuration• Possible exceptions:
not_authenticated, not_authorized
get_version
• Description: Retrieves the configuration version. It is visible in the Google spreadsheet, under Config sheet. This version is also inserted in a new case when it is created. When the configuration is updated and uploaded to Harmony, Harmony increments the version number if it detects changes in the rules and dialogs.
• Input parameters: only the default ones• Result: {config_version: N} – N is the version
number• Possible exceptions: not_authenticated,
not_authorized
get_version
get_reference_objects_names
• Description: Retrieves the names of the reference objects found in the currently uploaded configuration.
• Input parameters: only the default ones• Result: JSON object with property
“reference_objects_names” that is a JSON array containing string names of reference objects.
• Possible exceptions: not_authenticated, not_authorized
get_reference_objects_names
get_reference_object
• Description: Retrieves a whole reference object, all its keys and attributes.
• Input parameters:– name – the reference object name to retrieve
• Result: A JSON object containing the following properties:– possibleAttributes – an array of objects with a single property
“name”. These are the possible attributes a reference object can contain. Note that not all keys will have all attributes.
– keyName – the reference key name– object – the name of the reference object – sent in the name
parameter– keys – the reference keys as described in get_reference_data API
call• Possible exceptions: not_authenticated, not_authorized,
ref_object_not_found
ref_attrib_update
• Description: Updates a single reference attribute for a particular reference key. The update is propagated to the source of the reference data, e.g. Google spreadsheet.
• Input parameters:– object_name – the name of the reference object– key_val – the value of the reference key the updating reference
attribute is member of– attrib_name – the name of the updating reference attribute– new_val – the new value for the reference attribute
• Result: {success, true}• Possible exceptions: not_authenticated, not_authorized,
ref_object_not_found, ref_key_not_found
ref_attrib_update
ref_key_update
• Description: Allows updating a the whole reference key – all or any of its attributes. Note that it is not possible to update the value of the reference key. If a new value is provided for the reference key, a whole new reference key will be created. A common scenario is to search for existing reference key, change its value and possibly some of the attributes and to add it. This way the reference key is duplicated.
• Input parameters: – object_name – the name of the reference object– payload – JSON object
• key – JSON object representing the reference key– name– value
• attributes – JSON array containing JSON objects representing reference attributes– name– value
• Result: Object with properties:– success – with value “true”– status – with value either “updated” or “added”
• Possible exceptions: not_authenticated, not_authorized
ref_key_update