Logic Apps connectors provide quick access from Logic Apps to events, data, and actions across other apps, services, systems, protocols, and platforms. By using connectors in your logic apps, you expand the capabilities for your cloud and on-premises apps to perform tasks with the data that you create and already have. Azure Logic Apps connectors are powered by the connector infrastructure that runs in Azure. A workflow running on the new runtime can use these connectors by creating a connection, an Azure resource that provides access to these connectors.
A key capability in the redesigned Logic Apps runtime introduces the extensibility to add built-in connectors. These built-in connectors are hosted in the same process as the Logic App runtime and it provides higher throughput, low latency, and local connectivity. The connection definition file also contains the required configuration information for connecting through these built-in connectors. The preview release comes with the built-in connectors for Azure Service Bus, Azure Event Hub and SQL Server. The extensibility framework that these connectors are built on can be used to build custom built-in connectors to any other service that you need.
In this blog post, I am showing how we can leverage this extensibility framework to create a built-in CosmosDB connector with a trigger and no actions. In this example, whenever the new document is added in the lease collection or container of Cosmos DB, the Logic Apps trigger will fire and execute the Logic App with the input payload as Cosmos document. This built-in connector leverages the functionality of Azure function capability for Cosmos DB trigger based upon the Azure Function trigger binding. In general, you can add any action or function trigger as part of your own built-in connectors. Currently trigger capabilities are limited to Azure Function specific triggers only, in future the Logic app will support non-Azure function triggers also.
Built-in connector plugin model
The Logic Apps built-in connector extensibility model leverages the Azure Functions extensibility model to enable adding built-in connector implementations like Azure Functions extensions. This allows developers to write their connectors as Azure Functions extensions, build and package them as a NuGet for anyone to consume.
There are mainly two operation parts that a developer would need to implement:
- Operation Descriptions
Operation descriptions are metadata about the operations that the custom built-in connector implements. These are primarily used by the Logic Apps designer to drive the authoring and monitoring experience related to these connectors' operations. For example, designer uses operation descriptions to understand the input parameters required for a given operation as well as facilitate the generation of outputs property tokens based on the schema of the output of an operation.
- Operation Invocations
Logic Apps runtime will use these implementations at runtime to invoke the specified operation in the workflow definition.
In order to hook up with function runtime the new built-in connector extension need to be registered with the Azure Function runtime extensions. The details are discussed later in this blog.
CosmosDB Built-in Connector
Here in this sample connector, I am developing the CosmosDB built-in custom connector which has only one trigger and no actions are available. The details of the operations are described below:
|
Logic App Operation |
Operation details |
Description |
|
Trigger |
Receive Document |
The trigger is invoked when there are inserts or updates in the specified database and collection of CosmosDB. |
|
Action |
- |
No action operation are defined for this connector |
To develop your own built-in connector, you need to add the work flow webjob extension package. , I am creating the .NET Core 3.1 class library project in visual studio and added the Microsoft.Azure.Workflows.Webjobs.Extension package as Nuget reference to the project. The Service provider interface is implemented to provide the operations of the CosmosDB connector.
Service Provider interface implementation
The webjob extension Nuget package which was added to the class library project provides the service provider interface IServiceOperationsTriggerProvider which needs to be implemented.
As part of operation description, the IServiceOperationsTriggerProvider interface provides methods GetService() and GetOperations() which are required to be implemented by the custom built-in connector. These operations are used by the logic app designer to describe the actions/triggers by the custom built-in connector on the logic app designer surface. Please note that the GetService() method also specifies the connection parameters needed by the Logic app designer.
For action operation, you need to implement the InvokeActionOperation() method, which is invoked during the action execution. If you would like to use the Azure function binding for azure triggers, then you need to provide connection information and trigger bindings as needed by Azure function. There are two methods which need to be implemented for Azure function binding, GetBindingConnectionInformation() method which provides the connection information to the Azure function binding and GetTriggerType() which is same as “type” binding parameter for Azure function.
The picture below shows the implementation of methods as required by the Logic app designer and Logic app runtime.
The details of the methods which are required to be implemented are tabulated below:
|
Operation Methods |
Comments |
Example |
|
GetService() |
This is needed by Logic app designer. This is the high-level description of your service, which includes the service descriptions, brand color, Icon URL, connection parameters and capabilities etc. |
|
|
GetOperations() |
This is needed by Logic app designer, to get the list of operations that your service has implemented. This is based upon a swagger schema. |
|
|
InvokeOperation() |
This is invoked for every action operation during runtime. Here you can use any client (FTPClient, HTTPClient etc..) as needed by your custom built-in connector actions. If you are just implementing the trigger as in this case, then you do not need to implement this method. |
|
|
GetBindingConnectionInformation() |
These are the required connection parameters by trigger binding in case you are using the Azure function trigger type. |
|
|
GetFunctionTriggerType() |
If you are using the Azure function built-in triggers as Logic App trigger, then you need to return the string which is same as type in Azure function trigger binding. "type": "cosmosDBTrigger", |
|
Function Extensions and registration:
The function extension registration needs to be added as a startup job and register the service provider as part of service provider list, so that the built-in connector extension can be loaded during the function runtime start process.
Adding the converter is optional depending upon the type of data you need as an input to the built-in trigger. In this example I am converting the Document data type for Cosmos DB Documents to JObject array.
- Create startup job: To register the custom built-in connector as function extension, you need to create a startup class using [assembly:WebJobsStartup] assembly attribute and implementing IWebJobsStartup interface, refer the function registration for more details. In the configure method you need to register the extension and inject the service provider as shown below:
public class CosmosDbServiceProviderStartup : IWebJobsStartup
{
public void Configure(IWebJobsBuilder builder)
{
// Registering and extension
builder.AddExtension<CosmosDbServiceProvider>();
// DI the trigger service operation provider.
builder.Services.TryAddSingleton<CosmosDbTriggerServiceOperationProvider>();
}
}
- Register service provider: We need to register the service provider implementation as function extension. We are using the built-in Azure function Cosmos DB Trigger as a new trigger. Here in this example, we register the new Cosmos DB service provider for an existing list of service providers which are already part of Logic App extension.
[Extension("CosmosDbServiceProvider", configurationSection: "CosmosDbServiceProvider")]
public class CosmosDbServiceProvider : IExtensionConfigProvider
{
public CosmosDbServiceProvider(ServiceOperationsProvider serviceOperationsProvider, CosmosDbTriggerServiceOperationProvider operationsProvider)
{
serviceOperationsProvider.RegisterService(ServiceName, ServiceId, operationsProvider);
}
public void Initialize(ExtensionConfigContext context)
{
// Converts Cosmos Document list to JObject array.
context.AddConverter<IReadOnlyList<Document>, JObject[]>(ConvertDocumentToJObject);
}
}
- Add Converter: Logic app has implemented the generic way to handle any function built-in trigger using the JObject array, we may need (optional) to add a converter to convert the read only list of Azure Cosmos DB document into JObject array. Once the converter is ready as shown in above example, we need to register the converter as part of ExtensionConfigContext.
// Converts Cosmos Document list to JObject array.
context.AddConverter<IReadOnlyList<Document>, JObject[]>(ConvertDocumentToJObject);
The complete implementation of all three classes as mentioned above are given in the following code map diagram.
Testing the built-in connector:
You need to update the extensions.json in extension bundle to add the above NuGet reference. You can refer the add-extension.ps1 script.
Update the extension bundle to include the custom built-in connector.
Create the Logic App project and install the extension package given below:
dotnet add package "Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB" --version 1.0.0 --source $extensionPath
Alternatively, you can execute the PowerShell script add-extension.ps1 as given below in you Logic App project directory.
powershell -file add-extension.ps1 <CosmosDB output bin Nuget folder path> CosmosDB
Once you open the workflow in designer (make sure you close any func.exe process in case if it already running before opening the designer), you should be able to see the newly added connector.
You can now add connection string of Azure cosmos DB and add new document in the database under collection or lease collection to test the trigger by creating a simple logic app using the CosmosDB trigger.
Specifying the connection string.
Specify the database name and collection name for the trigger.
Execute F5 in VS code and invoke trigger by adding a new item using data explorer of your CosmosDB account as shown below to trigger the workflow.
The sample code can be downloaded from the repository.
https://github.com/Azure/logicapps-connector-extensions/tree/main/src/CosmosDB