Specification. HR-plus 8 Service Bus Integration - Overview

Transcription

1 Specification HR-plus 8 Service Bus Integration - Overview

2 Table of Contents 1. Document information History Introduction Scope Target audience Terms and Acronyms Service overview Integration pattern Messaging format Identification Header Handling null and excluded elements CRUD action on each entity Business Action Communication Subscribing to Service Bus NET code example Queues, Topics and Subscriptions Message properties Error handling Integration schemas Page 2 of 12

3 1. Document information Status Author Draft Stefan Vinqvist Reviewed by 1.1 History Date Version Shortname Comment STVI Initial draft STVI Updated to version STVI Updated to version 8.50 Page 3 of 12

4 2. Introduction This document describes the generic way for an External Master System to integrate with HR-plus 8 via Service Bus. It provides an overview of the integration pattern along with technical information common to all HR-plus 8 Service Bus integrations. 2.1 Scope HR-plus 8 uses the Microsoft Service Bus for Windows Server to integrate asynchronous incoming and outgoing messages. This document describes the formats and the way of communicating with the Service Bus. Integration API and basic functionality and flows of the HR-plus 8 system is included in this document. External system behaviour and requirements are outside the scope of this document. 2.2 Target audience This document assumes a basic understanding of integration patterns. It is primarily targetet towards a technical audience with experience in system integration. 2.3 Terms and Acronyms Term Service Bus XML XSD Definition Microsoft Windows Server Service Bus Extensible Markup Language XML Schema Definition Page 4 of 12

5 3. Service overview 3.1 Integration pattern The Service Bus offers message-driven integration by combining message queues with a publishsubscribe pattern. Messages that should be processed by HR-plus 8 are placed on a message queue by an external system. Messages that are generated by HR-plus 8 are published on a topic where thay can be retreived by an external system via a subscription to that topic. 3.2 Messaging format The message that shall be used when subscribing and publishing to the Service bus is XML-based specified in an XSD schema for each integration entity type (Person, Group, Department etc) Identification Every entity has in common that it uses a flexible way of handling ID:s. The ID of the entity has an attribute that defines the ID type. For instance, when importing data to HR-plus 8 via the Service Bus one can choose either HR-plus 8 internal ID (HRPlusId) to identify a record, or one of the other unique identification options depending on the entity. The identification option UseSystemConstraint will use a combination of underlying element values to find a unique identifier for the record. HR-plus 8 will always send the type HRPlusId as ID. However, that does not implicate that HR-plus 8 do not send the other elements. It implicates that it uses HRPlusId for identification. Page 5 of 12

6 3.2.2 Header Each message will contain a header for tracing data. The header has the following elements: SourceSystem The name of the sending system. This can be used to select a specific case type and flow based on configured Business Actions in the Administration module of HR-plus 8 web portal. SourceSystemTimeStamp The datetime when the message left the sending system. MessageId A unique identifier which should be unique among all messages. HR-plus 8 uses a GUID and we recommend other system that implements the format to use the same method. This ID is important for tracing messages and keeping track of asynchronous request-response situations. BusinessAction The main business action that requests the change. This can be used to select a specific case type and flow based on configured Business Actions in the Administration module of HR-plus 8 web portal. For more detail please refer to the chapter on Business Action. SchemaVersion The version of the schema Handling null and excluded elements Due to the fact that HR-plus 8 integrations should be based on changes, we need to explicitly explain how we handle excluded elements and nullable fields. Because of the above all elements, except ID definitions, needs to have minoccurs= 0 even though they are mandatory in HR-plus 8. To determine whether an element is mandatory or not we use the nillable flag in the xsd. The schemas contain the following combinations: minoccurs= 0 nillable= true This states that this field is a not mandatory field in HR-plus 8. minoccurs= 0 This states that this is a mandatory field in HR-plus 8. Nillable=false is the default value for XSD-elements. minoccurs= 1 or left out This states that is id definition and must always be populated. minoccurs= 1 is the default value for XSD-elements. Page 6 of 12

7 3.2.4 CRUD action on each entity As mentioned above HR-plus 8 uses the business event to keep track on the major event but these business events is not enough to keeping track on the changes at the entity level. Therefore HR-plus 8 has implemented the CRUD (Create, Read, Update, Delete) model on each entity. The Read action is however not applicable in this scenario. HR-plus 8 handles the below actions: Create A new instance of the entity is created and HR-plus 8 sends or receives data for the entity. All mandatory fields need to be populated. Update An existing instance is updated. HR-plus 8 sends or receives the ID definitions and the changed data. Merge Merge will result in either Create or Update depending on the existing data. If an existing instance is found using based on the identification provided in the received data, the existing instance is updated. If an existing instance is not found using based on the identification provided in the received data, a new instance is created. Note: Merge is currently only supported in the Person integration schema and its included subschemas. Delete An existing instance has been deleted. HR-plus 8 sends or receives only relevant ID definitions of the instance. Note: A deletion may result in a soft deletion in HR-plus 8, where the instance is regarded as deleted but not actually deleted due to historical tracking requirements Business Action Please note that this section applies to the Person integration schema only. Please refer to the online documentation on how to define Business Actions in the web portal. For messages that target the Person integration schema, it is possible to define two types of workflow for the resulting case management: Finalize Pause for completion Finalize Finalize is the default behaviour for case management of integration messages. This means that a case will be created and automatically finalized if data validation is successful. If no Business Actions are defined in the web portal, or if a message doesn t match any defined Business Actions, the case will be automatically finalized. Defined Business Actions can also have the Finalize attribute set to true, which means they will be automatically finalized Pause for completion Business Actions that have the Finalize attribute set to false will be halted when they reach the Started state in the case workflow. In that state, the case can be edited and finalized in the web portal Page 7 of 12

8 just like manually created cases. Cases will be assigned to the user defined for that specific Business Action. If a specific User is part of the XML header in the received data, this will override the user defined for the Business Action. Page 8 of 12

9 4. Communication 4.1 Subscribing to Service Bus When communicating with the service the following methods are supported: REST TcpNetBinding AMQP When using TcpNetBinding (as in the example below) one does not need to poll the Service Bus, as you need with the other methods. The TcpNetBinding supports push which means that when connected to the Service Bus the connected service gets the message delivered instantly as they are published. When communicating with the Service Bus, Bluegarden will provide with the following: Service Bus connection string and REST endpoint Shared Access Security Token The subscription name to subscribe to Entity path With the above parameters one will be able to set up a subscription and listen to the Service Bus with the method of choice. When communicating with the service bus it is important to: Set the transaction to OK if everything went well. Rollback the transaction if something went wrong. Microsoft recommends 10 retries. If the retry limit has been reached, place the message as a dead letter with an informative error message. To read more about connection to Microsoft Windows Server Service Bus we recommend the following articles (applies to both Azure Service Bus and Service Bus for Windows Server): REST: General: NET code example In order to connect to the service bus from a.net application we recommend that you first install the Nuget package: Page 9 of 12

10 The below code snippet is an example on how one can subscribe to the Service Bus with TcpNetBinding: static void Main(string[] args) { const string keyname = "Sender"; const string securitytoken = "securitytoken"; const string servicebusconnectionstring = "servicebusconnectionstring"; const string suscriptionname = "suscriptionname"; const string entitypath = "entitypath"; var tokenprovider = TokenProvider.CreateSharedAccessSignatureTokenProvider(keyName, securitytoken); var factory = MessagingFactory.Create(serviceBusConnectionString, tokenprovider); var receiver = factory.createmessagereceiver(string.format("{0}/{1}",entitypath, suscriptionname)); receiver.onmessage(handlebrokeredmessage, new OnMessageOptions { AutoComplete = false, MaxConcurrentCalls = 1 }); } private static void HandleBrokeredMessage(BrokeredMessage brokeredmessage) { //Deserialize the brokered message in to class object using (var reader = new StreamReader(brokeredMessage.GetBody<Stream>())) { var serializer = new XmlSerializer(typeof (Person)); var hrplusperson = serializer.deserialize(reader) as Person; try { //Then do some stuff brokeredmessage.complete(); } catch (Exception e) { brokeredmessage.deadletter("error communicating with the service bus: ", e.message); throw; } } Queues, Topics and Subscriptions Incoming messages from external systems to Service Bus are placed on a pre-defined queue. Messages on a queue are processed on a First In, First Out (FIFO) basis. This provides a loose coupling between the external system and HR-plus 8, allowing for independent upgrades and maintenance windows. Topics are used to publish messages from Service Bus to an arbitrary number of Subscriptions (consumers). An external system subscribes to a pre-defined topic and receives all messages published to that topic. Subscriptions can apply filtering in order to receive a subset of all published messages. This can be useful if an external system only wants to retreive messages generated as a result of a successful import Message properties Messages that are published on a topic are decorated with some custom properties to facilitate filtering and tracing. The custom properties are: Key name Type Example value SourceSystem String HRPlus8 Page 10 of 12

11 SourceSystemTimeStamp DateTime :47:11 MessageId String f99b26bd-bdfd-42a6-bffaa62d8de73f27 BusinessAction String AdditionsDeductions SchemaVersion String Error handling Errors in import messages (from external system to Service Bus) are placed as error messages on the corresponding topic. A custom property is added to the message: Key name Type Example value ErrorDescription String Employment with HrPlusId not found If an external system detects errors in a message, the message should be placed as an error message on the corresponding queue. The custom property above should be added to the message with useful information. It is the responsibility of the sending system to check the queue/topic for error messages and correct and re-send the message. Page 11 of 12

12 5. Integration schemas HR-plus 8 supports external data integration for the following entities: Person (including all sub-entities for Employee and Employment) Groups Departments Positions AccountingDimensionValues Each schema is documented in separate documents. Schemas also have their own SchemaVersion lifecycles. Page 12 of 12