Event Streaming

Introduced in Version 13

Event Streaming enables inter site communications between two or more sites. You can subscribe to Document Types and stream Documents between different sites.

For Example: Consider you have more than one Company hosted on different sites, one among them is the main site where you want to do ledger posting and on other sites, the Sales Invoices are generated. You can use Event Streaming in this case. For this, your child company sites can subscribe to the main company site for Item, Customer, and Supplier Document Types. The main Company in turn can subscribe to the child companies for Sales Invoices.

To access Event Streaming, go to:

Home > Automation > Event Streaming

1. Prerequisites

A common user must be created on both sites in order to access the site and serve as an Event Subscriber before creating an Event Producer. Make that the user has the appropriate rights to create, update, and delete the subscribed Doc Types and is a System Manager.

2. How to set up Event Streaming

Let's use two websites to illustrate the procedure. both http://testsite producer:8000 and http://testsite:8000 (Producer site)

2.1 Obtain the Event Subscriber's keys from the Producer Site

1. Go to the User list on the producer site at http://testsiteproducer:8000.
2. Open the user document that you will use to subscribe to events. Scroll down to the "API Access" section. Create keys for the user by selecting the Generate Keys button in that area. You'll receive a prompt with the user secret; copy it and keep it on you. An API key will also be generated.

2.2 Generate Keys for the Event Subscriber on the Consumer Site

1. Go to the User list on the consumer site at http://test site:8000 and follow the instructions from the previous step.

2.3 Create an Event Producer on the Consumer Site

1. You should subscribe to the website known as the Event Producer. For the website from which you want to get updates, create an Event Producer document.
2. Visit the Consumer Site at http://test site:8000 and select Home > Automation > Event Streaming > Event Producer.
3. In the field labeled "Producer URL," type the website's URL (in this case, http://testsiteproducer:8000).
4. The Event Producer Document Types table should be updated with all the Document Types you choose to subscribe to.
5. Check the "Use Same Name" checkbox in the table next to the required Document Type if you want the newly created documents to have the same name as those on the distant Event Producer site.
6. The user who will be utilized to create the documents fetched from the Event Producer should be entered in the Event Subscriber box. Before creating the Event Producer, you must first create the same user both on the site for Event Consumers and Event Producers.
7. Copy and paste the API key and API secret that you created in step 2.1 into the corresponding slots.
8. Save.
9. After saving, the producer site (http://testsiteproducer:8000) creates an Event Consumer. In this procedure, the user's login credentials from the consumer site are automatically copied to the event consumer document on the producer site.

Note: If at all the API Secret is changed for the users on any of these sites, you will have to manually update the keys in the Event Producer as well as the Event Consumer on both the sites.

2.4 Approve Event Consumer on the Event Producer site

1. After the Event Producer has been created, an Event Consumer automatically gets created on the producer site. By default, all the Subscribed Document Types have the status as 'Pending'. In order to enable the Event Consumer to consume the documents of these Document Types, their Status needs to be updated to 'Approved'.
2. Go to: Home > Automation > Event Streaming > Event Consumer.
3. You can see every Document Type that the Event Consumer has subscribed to after you open the Event Consumer document. For each Document Type that you want to authorize for consumption, change the status from "Pending" to "Approved." If you do not want the papers of that Document Type to be consumed, you can alter the status to "Rejected."
4. Save.

Note: Document updates for Subscribed Document Types won't be synced unless they are Approved.

2.5 Offline access with single site

You could set up offline syncing by following these steps if you have some locations with poor internet connectivity, such as a store in a distant area where sales invoices are generated, and you wish to sync these invoices from the store to the hosted account:

1. Set up a local instance of Geer ERP. For a local setup, you can refer to this instructions.
2. You must have a hosted account set up with your business.
3. Now on the hosted account, establish an event producer and set the producer URL to the URL of your local account.
4. In the Event Producer Document Types child table, add any doctypes you wish to sync.
5. endorsing the doctypes

3. Features

3.1 Unsubscribe from the updates

Check unsubscribe against the doctype as an Event Consumer to stop receiving updates for any doctypes you have previously registered to. Once you unsubscribe, the producer site will no longer send you updates for that specific doctype.

3.2 Event Update Log

Every create, update, and delete activity for documents that have users on the Event Producer site is recorded in the "Event Update Log." Viewing the Event Update Log requires:

Access the Event Update Log by going to Home > Automation > Event Streaming.

• The Update Type, Document Type, Document Name, and the whole document (as JSON) are logged for the "Create" type.
• The updated data (difference between the prior state and current state of the document) is logged for the 'Update' type along with the Update Type, Document Type, Document Name, and Document Name.
• Only the Update Type, Document Type, and Document Name are logged for the "Delete" type.

3.3 Event Sync Log

The Event Sync Log, like the Update Log, records each document that is synchronized from the Event Producer to the Event Consumer website. Viewing the Event Sync Log entails:

Access the Event Sync Log by going to Home > Automation > Event Streaming.

An event that has successfully synchronized produces a log file that contains:

• Update Type: Create, Update or Delete
• Status: Sync Status
• DocType
• Event Producer: The site URL from where the document was created
• Document Name
• Remote Document Name: If 'Use Same Name' is unchecked
• Use Same Name
• Data: The document data as JSON

The following fields are also included in a log document created by a failed event:

• Error: The error that prevented the document from being synchronized.

• Resync Button: Additionally, a "Resync" button is provided in order to resync the unsuccessful event.

3.4 Dependency Syncing

Dependencies exist between specific document types. For instance, the Item and Customer must be present in the current site before syncing a Sales Invoice. Item and Customer are hence prerequisites for the sales invoice. This is taken care of by Event Streaming's on-demand dependency synchronization. Every time a document needs to be synced, a dependency check is performed first (Link fields, Dynamic Link fields, Child Table fields, etc.). If this condition is not met, i.e., the dependent document (for example, an item) is not present on your customer site, it will be synchronized first, followed by the sales invoice.

Syncing a sales invoice with an item dependence, for instance

3.5 Naming Configuration

To allow documents to have the same name on both the Event Producer and Event Consumer sites, select the "Use Same Name" checkbox. The document will be created using the current site's naming standards if this is not checked.

Note: For Document Types that have naming series, it is advised to keep the 'Use Same Name' checkbox unchecked, to prevent naming conflicts. If this is unchecked, the Documents are created by following the naming conventions on the current site and the 'Remote Site Name' and 'Remote Document Name' custom fields are set in the synced document to store the Event Producer site URL and the document name on the remote site respectively.

3.6 Mapping Configuration

Use Event Streaming with Mapping Configuration if you wish to stream documents between a Geer ERP instance and another Frappe app for a certain Document Type with the same or different structures, or if field names are different in both sites.

You must first create a Document Type Mapping before you can do this.

Go to: to obtain Document Type Mapping.

Home > Automation > Event Streaming > Document Type Mapping.

3.6.1 Mapping for DocTypes with similar structure

• Mapping Name: Give the mapping a distinctive name.
• Local Document Type: Your current site's Document Type
• Remote Document Type: The Document Type that you want to sync from the Event Producer website

In the child table for the field mapping:

• Local Fieldname: the fieldname in your current site's Local Document type.
• Remote Fieldname: The fieldname that you want to map to the local field on the Event Producer site's Remote Document type. The remote fieldname's value is copied to the local fieldname during the sync process.

3.6.2 Default value for some field

Set the same in the default value field if your field is not mapped to any other remote fieldnames and you want it to always contain the same value. Even if you have set the remote fieldname, if the "Default Value" has been selected, it will be set if the remote field's value cannot be located during the sync.

3.6.3 Mapping for DocTypes having child tables

You must establish a new Document Type Mapping for the fields of the child table if the field you are attempting to map is a child table.

• Mapping Type: Choose the Child Table mapping type.
• Mapping: Choose the document you made for the child table called Document Type Mapping.

3.6.4 Mapping for DocTypes having dependencies (Link, Dynamic Link fields)

You must create a different document type mapping in order to sync the dependencies if the document types you are attempting to map have any form of dependencies, such as Link or Dynamic Link fields.

Take Opportunity as an example, and let's say that Geer ERP Opportunity is the remote doctype. Party name, a field in Opportunity's Link field for Doc Type Lead, is mapped to full name in Geer ERP Opportunity's Data field. This Lead must be established during the sync in order for the primary Opportunity to sync. Therefore, you must also configure a mapping for this Link Field.

• Mapping Type: The Mapping Type in this instance is Document.
• Mapping: Select the newly created mapping.
• Remote Value Filters: The filters that will precisely retrieve the remote document to be mapped must be specified. The remote Doc Type in this instance is Geer ERP Opportunity, and it can be uniquely retrieved using the user's name, phone number, and country.

The format is:

{ "remote fieldname": "field or expression from where we will get the value for that fieldname"}

If you want to fetch the value from somewhere, start the expression with eval:

Like in this case it is: eval:frappe.db.get_value('Global Defaults', None, 'country')

Finally, pick the Document Type Mapping you just generated by enabling the "Has Mapping" option in Event Producer's Event Configuration child table against the necessary Document Type.

3.6 Conditional Events Configuration

You can set the requirements for them if you are in a situation where you do not want to deliver the consumer all of the documents in a given doctype.

You can declare them in the Producer/Consumer document, for instance, if you only want to emit public Note documents.

If a document satisfies a condition down the line in its lifetime, all the old Event Update Logs are synced to the consumer

Consider still another instance. Just the submitted Sales Invoices are what you want to sync. As the condition, you can define document status. Not until they are filed will the invoices be synchronized.

Within the Update Log page, you can view the Consumers for each update log.

You can connect a custom function if you require more precise control over the circumstances. With the following parameters: consumer, doc, and update log, your function will be called. For instance, you might want to sync just odd notes.

The condition might therefore be stated as follows: