Your SlideShare is downloading. ×
0
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Harmony API developers documentation (version 2.2)
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Harmony API developers documentation (version 2.2)

550

Published on

The Harmony API provides easy access for development languages like JAVA and PHP, to functions - such as business rules, workflow, dialog flows, authorization, emailing, mapping etc. …

The Harmony API provides easy access for development languages like JAVA and PHP, to functions - such as business rules, workflow, dialog flows, authorization, emailing, mapping etc.
This document describes all features - with samples.

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
550
On Slideshare
0
From Embeds
0
Number of Embeds
4
Actions
Shares
0
Downloads
5
Comments
0
Likes
0
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. Harmony API Developers documentation Version 2.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
  • 3. 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.
  • 4. 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
  • 5. 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.
  • 6. 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
  • 7. 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.
  • 8. No config API calls
  • 9. 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.
  • 10. get_all_lucidchart_diagrams
  • 11. 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.
  • 12. get_lucidchart_diagram
  • 13. 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.
  • 14. create_empty_config
  • 15. 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}
  • 16. 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
  • 17. get_public_token
  • 18. 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.
  • 19. login
  • 20. 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.
  • 21. 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
  • 22. logout
  • 23. 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
  • 24. get_dialog_names
  • 25. 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
  • 26. get_work_items
  • 27. 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
  • 28. get_case_ids
  • 29. 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_ob jects, no_event_name, event_not_found, unkown_facts, dialog_withdrawn, dialo g_already_submitted
  • 30. submit_dialog
  • 31. 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
  • 32. submit_for_predictions
  • 33. 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
  • 34. get_predictions
  • 35. 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_na me_not_found, key_not_found
  • 36. get_dialog
  • 37. get_case_data • Description: Retrieves all case data for the case. Readonly 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
  • 38. get_case_data
  • 39. 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
  • 40. get_case_history
  • 41. 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
  • 42. get_facts_for_history_record
  • 43. 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
  • 44. search
  • 45. 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
  • 46. get_meta_info
  • 47. 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
  • 48. test_predictions
  • 49. 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
  • 50. get_reference_data
  • 51. 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
  • 52. get_correlation_data
  • 53. 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
  • 54. 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}
  • 55. flush • Description: Flushes the loaded configuration. • Input parameters: only the default ones • Result: {success, true} or exception • Possible exceptions: not_authenticated, not_authorized
  • 56. flush
  • 57. 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
  • 58. 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
  • 59. get_version
  • 60. 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
  • 61. get_reference_objects_names
  • 62. 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
  • 63. 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_fo und, ref_key_not_found
  • 64. ref_attrib_update
  • 65. 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 – – • attributes – JSON array containing JSON objects representing reference attributes – – • name value name value Result: Object with properties: – success – with value “true” – status – with value either “updated” or “added” • Possible exceptions: not_authenticated, not_authorized
  • 66. ref_key_update

×