Design Principles and Functionality of the OBP Rest API

3.3.1 Wildcard Searches

Wildcard searches search in a defined depth, i.e. a range of database tables reached with a defined number of joins, on a predefined list of columns that are available for searches.

• Spaces are token delimiters. To get a token with two words, use quotations. Valid quotations are ' and ". They cannot be escaped directly, but one of them can be used inside a pair of the others.
  • text
  • 'text1 text2'
  • 'text1 "textStartingWithDoubleQuotes'
• Tokens are separated by space. All tokens are combined with 'and' unless 'or' is explicitly used as a token.
  • ' ' (space) -> and
  • ' or ' -> or
  • 'text1 text2' or text3
• Tokens may be excluded: prepend token with -.
  • -text1
  • -'text1 text2'
• Tokens (string) may be searched exactly: prepend token with + (%2B on URL). Note: -+ is available to exclude exact matches.
  • +text1
  • +'text1 text2'
• Tokens (DateTime) may be compared: prepend token with > or < (on URL: %3E or %3C, respectively).
  • <23.09.2020
  • '>23.09.2020 10:12:13'
• Brackets may be used to group tokens.
  • (a b) or (c d)
• The search range for tokens can be restricted to tables or columns using square brackets. Inside the brackets, "tab" is used for table names, "col" is used for column names. These are valid search strings restricting the search to a tablename, a columnname, or both.

  Search expression	Restriction		Search text	Remark
  	Table	Column
  [tab;tablename;col;columnname;searchtext]	tablename	columnname	searchtext	The search is restricted to table "tablename" and column "columnname".
  [tab;tablename;searchtext]	tablename		searchtext	The search is restricted to table "tablename".
  [col;columnname;searchtext]		columnname	searchtext	The search is restricted to column "columnname" in any table searched.
  [tab;Campaign;col;Name;campaign xxx]	Campaign	Name	campaign xxx	The search is restricted to exactly one column in one table.
  [col;Name;campaign xxx]		Name	campaign xxx	The search is restricted to any table with a column named 'Name'.

3.7.1 KeepMissingDetailsOnUpdate

In order to delete non-desired child/subordinate entities from the database, do not provide them in a JSON passed in and set the value of the KeepMissingDetailsOnUpdate key to false while updating/modifying the corresponding parent entity. Once KeepMissingDetailsOnUpdate has been set, it will have the following impact on the delete behavior depending on the parent it has been applied for:

Parent Entity	JSON Example	Deletion Effects
Campaign		OrgColumns All OrgColumns (except those provided in JSON, in our example: the one with Id "1") linked to Campaign with Id "1" will be deleted. CampaignElements All CampaignElements linked to Campaign with Id "1" will be deleted, since none of them is referenced in JSON. ObpFiles Analogous to CampaignElements.
CampaignElement		OrgColumns All OrgColumns (except those provided in JSON, in our example: the one with Id "4") linked to campaignElement with Id "1" will be deleted. Plans All Plans linked to CampaignElement with Id "1" will be deleted, since none of them is referenced in JSON. ObpFiles Analogous to Plans.
<other tables>		Analogous to the tables above.

7.1.1 Matching Events

• A required name field to enable usage of the event definition within multiple rules.
• Two required fields that must have exactly the value used in the event to be matched:
  • The event type.
  • The table id, i.e. the id of the data table on which the event occured.
• Two optional attributes. These attributes can specify values the data item referenced in the event has before and after the event is thrown, e.g. the state of an object (old value and/or new value).

7.1.2 Defining Actions

These common actions are available:

• A required name field to enable usage of the action within multiple rules.
• A required field specifying the action.
• An optional attribute. This attribute can specify a data item reference for dynamic action data, e.g. to reference the actual state of an object. Please note that the actual state is the state availabe during rule processing, which might be updated after the event is thrown.

7.1.3 Matching of item data

• A required name field to enable usage of the attribute.
• A required field 'TableName'. It may be empty.
• A required field 'ColumnName'. It may be empty.
• An optional field 'value'.

• Events contain (more precise, can contain depending on the event) values before and after event execution.
• Event definitions may contain attributes for comparing the values before and after event execution.
• 'TableName' and 'ColumnName' are not used for matching of event definitions.

To refer to item data within messages, there are two possibilities:

1. Use the message content.
   Use square brackets within the content of the message. The text inside the square brackets is used to find the item data. These are the valid usages:

   Starting string	Context	Description
   Object::	Get property from object.	Read a property value directly from an item data, e.g. [Object::Id] or [Object::BuyerId].
   Account::	Get Id of account for email / notifications.	For message elements "mail to" and mail cc", an account id is required. To define elements sending mails to fixed accounts (not depending on item data), pass in [Account::<username>].
   ParameterNew::	Use event parameterNew.	Directly insert the value provided in the event as "ValueNew" into the message. This is used to provide special data, e.g. an automatically created password, to an email.

   
   
2. Use an empty message content, and provide columns TableName and ColumnName.
   In this case, the data table is navigated to from the item data of the event, using the "TableName". "TableName" may contain a hierachy of navigations. This hierarchy always starts with the table name of the item data. In the resulting table, property "ColumnName" is used.
   Example: to find the last name of the buyer of a campaign in a campaign-related event, use "TableName" = "Campaign.Buyer.Person" and "ColumnName" = "LastName".

7.1.4 Examples

Send a mail when a password is reset:
{
  "OrganizationId": 1,
  "Name": "AccountResetPassword",
  "EmDefinition": { "OrganizationId": 1, "Name": "AccountResetPassword", "EmEventType": "AccountResetPassword", "DbTableId": "Account" },
  "EmAction" : { "OrganizationId": 1, "Name": "SendMail", "ActionType": "SendMessage" },
  "Active" : true,
  "EmMessageElements": [
    { "OrganizationId": 1, "Name": "MailT_AccountResetPassword", "EmContentType": "MailTo" , "Content": "[Object::Id]" },
    { "OrganizationId": 1, "Name": "MailC_AccountResetPassword", "EmContentType": "MailContent", "Content": "Password: @[ParameterNew::]@" },
    { "OrganizationId": 1, "Name": "MailS_AccountResetPassword", "EmContentType": "MailSubject", "Content": "AccountResetPassword Username=@[Object::Username]@, Id=@[Object::Id]@." }
  ]
}

Notify platform admin after an organization is created:
{
  "Id": 19,
  "OrganizationId": 1,
  "Name": "CreateOrganizationNotify_OrgAdmin",
  "EmDefinition": { "OrganizationId": 1, "Name": "OrganizationChangeActiveState", "EmEventType": "OrganizationChangeActiveState", "DbTableId": "Organization" },
  "EmAction" : { "OrganizationId": 1, "Name": "SendMail", "ActionType": "SendMessage" },
  "Active" : false,
  "EmMessageElements": [
    { "OrganizationId": 1, "Name": "MailT_OrganizationCreate", "EmContentType": "MailTo" , "Content": "[Object::Id]" },
    { "OrganizationId": 1, "Name": "MailS_OrganizationCreate", "EmContentType": "MailSubject", "Content": "OrganizationChangeActiveState [Object::Name]@, Id=@[Object::Id]@, set to state @[ParameterNew::]@, state=@[Object::Active]@." },
  ]
}