docs/jbpm-docs/src/main/asciidoc/DomainSpecificProcesses/ServiceRepository-section.adoc - incubator-kie-docs - Git at Google


 = Service Repository

 A lot of these domain-specific services are generic, and can be reused by a lot of different users.
 Think for example about integration with Twitter, doing file system operations or sending email.
 Once such a domain-specific service has been created, you might want to make it available to other users so they can easily import and start using it.

 A service repository allows you to import services by browsing the repository looking for services you might need and importing these services into your workspace.
 These will then automatically be added to your palette and you can start using them in your processes.
 You can also import additional artefacts like for example an icon, any dependencies you might need, a default handler that will be used to execute the service (although you're always free to override the default, for example for testing), etc.

 To browse the repository, open the wizard to import services, point it to the right location (this could be to a directory in your file system but also a public or private URL) and select the services you would like to import.
 For example, in Eclipse, right-click your project that contains your processes and select "Configure ... -> Import jBPM services ...".  This will open up a repository browser.
 In the URL field, fill in the URL of your repository (see below for the URL of the public jBPM repository that hosts some common service implementations out-of-the-box), or use the "..." button to browse to a folder on your file system.
 Click the Get button to retrieve the contents of that repository.

 image::DomainSpecificProcesses/ImportService.png[]

 Select the service you would like to import and then click the Import button.
 Note that the Eclipse wizard allows you to define whether you would like to automatically configure the service (so it shows up in the palette of your processes), whether you would also like to download any dependencies that might be needed for executing the service and/or whether you would like to automatically register the default handler, so make sure to mark the right checkboxes before importing your service (if you are unsure what to do, leaving all check boxes marked is probably best).

 After importing your service, (re)open your process diagram and the new service should show up in your palette and you can start using it in your process.
 Note that most services also include documentation on how to use them (e.g.
 what the different input and output parameters are) when you select them browsing the service repository.

 Click on the image below to see a screencast where we import the Twitter service in a new jBPM project and create a simple process with it that sends an actual tweet.
 Note that you need the  necessary Twitter keys and secrets to be able to programmatically send tweets to your Twitter account.
 How to create these is explained https://docs.jboss.org/jbpm/v6.0/repository/Twitter/[here], but once you have these, you can just drop them in your project using a simple configuration file.

 image::DomainSpecificProcesses/Twitter.png[link="http://people.redhat.com/kverlaen/twitter-repository.swf"]

 == Public jBPM service repository

 We are building a public service repository that contains predefined services that people  can use out-of-the-box if they want to:

 https://docs.jboss.org/jbpm/v6.0/repository/

 This repository contains some integrations for common services like Twitter integration or file system operations that you can import.
 Simply point the import wizard to this URL to start browsing the repository.

 If you have an implementation of a common service that you would like to contribute to the community, do not hesitate to contact someone from the development team.
 We are always looking for contributions to extend our repository.

 == Setting up your own service repository

 You can set up your own service repository and add your own services by creating a configuration file that contains the necessary information (this is an extended version of the normal work definition configuration file as described earlier in this chapter) and putting the necessary files (like an icon, dependencies, documentation, etc.) in the right folders.

 The extended configuration file contains the normal properties (like name, parameters, results and icon), with some additional ones.
 For example, the following extended configuration file describes the Twitter integration service (as shown in the screencast above):

 [source]
 ----
 import org.drools.core.process.core.datatype.impl.type.StringDataType;
 [
   [
     "name" : "Twitter",
     "description" : "Send a Twitter message",
     "parameters" : [
       "Message" : new StringDataType()
     ],
     "displayName" : "Twitter",
     "eclipse:customEditor" : "org.drools.eclipse.flow.common.editor.editpart.work.SampleCustomEditor",
     "icon" : "twitter.gif",
     "category" : "Communication",
     "defaultHandler" : "org.jbpm.process.workitem.twitter.TwitterHandler",
     "documentation" : "index.html",
     "dependencies" : [
       "file:./lib/jbpm-twitter.jar",
       "file:./lib/twitter4j-core-2.2.2.jar"
     ]
   ]
 ]
 ----


 * The name property is the unique name for your service
 * The parameters property defines the service data inputs giving them a name and a type
 * You can similarly to input parameters also define the "results" property for service data ouputs (same structure applies)
 * The icon property should refer to a file with the given file name in the same folder as
   the extended configuration file (so it can be downloaded by the import wizard and used in the process
   diagrams).  Icons should be 16x16 GIF files.
 * The category property defines the category this service should be placed under when
   browsing the repository.
 * The defaultHandler property defines the default handler implementation (i.e. the Java class that implements the `WorkItemHandler` interface and can be used to execute the service).  This can automatically be registered as the handler for that service when importing the service from the repository. You can also use mvel to resolve the default handler expression which has the additional benefit of being able to resolve the handlers parameters, for example:
 [source]
 ----
 "defaultHandler" : "mvel: new org.jbpm.process.workitem.twitter.TwitterHandler(ksession)",
 ----
 Some of the available named parameters you can use are:
 [source]
 ----
 ksession
 taskService
 runtimeManager
 classLoader
 entityManagerFactory
 ----
 * The documentation property defines a documentation file that describes what the service does and how it works. This property should refer to a HTML file with the given name in the same folder as the extended configuration file (so it can be shown by the import wizard when browsing the repository).
 * The dependencies property defines additional dependencies that are necessary to execute this service. This usually includes the handler implementation JAR, but could also include additional external dependencies. These dependencies should also be located on the repository on the given location (relative to the folder where the extended configuration file is located), so they can be downloaded by the import wizard when importing the service. If the necessary dependencies are located in a maven repository you can define them via the mavenDependencies property, for example:
 [source]
 ----
 "mavenDependencies" : [
   "org.jbpm:jbpm-twitter:1.0",
   "org.twitter4j:twitter4j-core:2.2.2"
 ]
 ----

 The root of your repository should also contain an [path]_index.conf_ file that references all the folders that should be processed when searching for services on the repository. This file could look as follows:
 [source]
 ----
 Email
 FileSystem
 ESB
 FTP
 Google
 Java
 Jabber
 Rest
 RSS
 Transform
 Twitter
 ----

 Each of those folders should then contain:

 * An extended configuration file with the same name as the folder (e.g. [path]_Twitter.conf_)
  that defines the service task
 * The icon as referenced in the configuration file
 * The documentation as referenced in the configuration file
 * The dependencies as referenced in the configuration file (for example in a lib folder)
 You can create your own hierarchical structure, because if one of those folders also contains an [path]_index.conf_ file, that will be used to scan additional sub-folders.
 Note that the hierarchical structure of the repository is not shown when browsing the repository using the import wizard, as the category property in the configuration file is used for that.

 == Programatically interacting with the service repository
 jBPM provides classes in the org.jbpm.process.workitem package which allows you to connect and retrieve your service information. For example:
 [source]
 ----
 Map<String, WorkDefinitionImpl> workitemsFromRepo =
   WorkItemRepository.getWorkDefinitions("https://docs.jboss.org/jbpm/v6.0/repository/");
 ----
 This will provide you with all services defined in the repository (and declared in your index.conf file). You can then get more detailed information about each of services in the repository using their name as declared in the service wid file, for example when using the twitter wid configuration from above we could do:
 [source]
 ----
 workitemsFromRepo.get( "Twitter" ).getName();                 // "Twitter"
 workitemsFromRepo.get( "Twitter" ).getDescription();          // "Send a Twitter message"
 workitemsFromRepo.get( "Twitter" ).getDefaultHandler();       // "org.jbpm.process.workitem.twitter.TwitterHandler"
 workitemsFromRepo.get( "Twitter" ).getDependencies();         // String["file:./lib/jbpm-twitter.jar","file:./lib/twitter4j-core-2.2.2.jar"]
 ...
 ----
 or you could for example check if the correct version of the service you need is contained in the repository:
 [source]
 ----
 if( workitemsFromRepo.containsKey( "Twitter" ) && workitemsFromRepo.get( "Twitter" ).getVersion().equals( "1.0" )) {
   // do something
 }
 ----
 Currently all operations are read-only. There isn't a way to update the service repository automatically.

 == Defining extended service configuration with JSON
 The previous extended configuration example for the Twitter service was defined with the default mvel configuration. It is also possible to do this with JSON and the Twitter example would look like this:
 [source]
 ----
 [
   [
     "java.util.HashMap",
     {
       "name":"TestServiceFour",
       "displayName":"Twitter",
       "description":"Send a Twitter message",
       "parameters":[
         "java.util.HashMap",
         {
           "Message":["org.drools.core.process.core.datatype.impl.type.StringDataType", {}]
         }
       ],
       "eclipse:customEditor":"org.drools.eclipse.flow.common.editor.editpart.work.SampleCustomEditor",
       "defaultHandler" : "org.jbpm.process.workitem.twitter.TwitterHandler",
       "documentation" : "index.html",
       "dependencies":[
         "java.util.ArrayList", ["file:./lib/jbpm-twitter.jar", "file:./lib/twitter4j-core-2.2.2.jar"]
       ]
     }
   ]
 ]
 ----
 In your service repository you can define the extended configuration of your services with mvel or JSON (or have some defined in one way and some in the other as well).
 Defining the extended configuration with JSON might have some benefits if being read by custom web-based clients for example.

 == Installing services from the service repository
 The Workbench provides two ways of installing services from the user defined service repositories:

 * Automatic install - allows you to specify the repository URL and a list of services (via their unique names specified in the wid) that will get installed and be ready for use when
 you create/open a business process in the Workbench. For example let's say we have a service repository available at http://mysite.com/myservicerepo and there we define as previsously mentioned two services, namely BuyStock and SellStock.
 To have these services automatically installed in the Workbench you can add the following startup parameters:
 [source]
 ----
 AS/bin/standalone.sh -Dorg.jbpm.service.repository=http://mysite.com/myservicerepo -Dorg.jbpm.service.servicetasknames=BuyStock,SellStock
 ----

 Or if you wanted just the SellStock service installed:
 [source]
 ----
 AS/bin/standalone.sh -Dorg.jbpm.service.repository=http://mysite.com/myservicerepo -Dorg.jbpm.service.servicetasknames=SellStock
 ----

 Currently there is no install-all option available so service names must be individually specified.
 When creating a new or opening an existing business process then the Workbench will attempt to install the specified services from the provided repository URL.
 This will install the service wid configuration, the spcified icon (if there is one or if not the Workbench will provide a default one for it), the default handler will be added to the deployment descriptor of your Workbench project as well as the specified maven dependencies in the service configuration will be added to the Workbench project pom.xml file.
 Please note that currently there is no option to specify maven repositories via the service task configuration so they must be added via the Workbench in its POM Editor by the users.

 * Manual installation through the Workbench - allows users to install one or more services from the services through the Workbench. You can find detailed information on how to do that in the <<jBPMDesigner,Process Designer Chapter>>.

	= Service Repository

	A lot of these domain-specific services are generic, and can be reused by a lot of different users.
	Think for example about integration with Twitter, doing file system operations or sending email.
	Once such a domain-specific service has been created, you might want to make it available to other users so they can easily import and start using it.

	A service repository allows you to import services by browsing the repository looking for services you might need and importing these services into your workspace.
	These will then automatically be added to your palette and you can start using them in your processes.
	You can also import additional artefacts like for example an icon, any dependencies you might need, a default handler that will be used to execute the service (although you're always free to override the default, for example for testing), etc.

	To browse the repository, open the wizard to import services, point it to the right location (this could be to a directory in your file system but also a public or private URL) and select the services you would like to import.
	For example, in Eclipse, right-click your project that contains your processes and select "Configure ... -> Import jBPM services ...". This will open up a repository browser.
	In the URL field, fill in the URL of your repository (see below for the URL of the public jBPM repository that hosts some common service implementations out-of-the-box), or use the "..." button to browse to a folder on your file system.
	Click the Get button to retrieve the contents of that repository.

	image::DomainSpecificProcesses/ImportService.png[]

	Select the service you would like to import and then click the Import button.
	Note that the Eclipse wizard allows you to define whether you would like to automatically configure the service (so it shows up in the palette of your processes), whether you would also like to download any dependencies that might be needed for executing the service and/or whether you would like to automatically register the default handler, so make sure to mark the right checkboxes before importing your service (if you are unsure what to do, leaving all check boxes marked is probably best).

	After importing your service, (re)open your process diagram and the new service should show up in your palette and you can start using it in your process.
	Note that most services also include documentation on how to use them (e.g.
	what the different input and output parameters are) when you select them browsing the service repository.

	Click on the image below to see a screencast where we import the Twitter service in a new jBPM project and create a simple process with it that sends an actual tweet.
	Note that you need the necessary Twitter keys and secrets to be able to programmatically send tweets to your Twitter account.
	How to create these is explained https://docs.jboss.org/jbpm/v6.0/repository/Twitter/[here], but once you have these, you can just drop them in your project using a simple configuration file.

	image::DomainSpecificProcesses/Twitter.png[link="http://people.redhat.com/kverlaen/twitter-repository.swf"]

	== Public jBPM service repository

	We are building a public service repository that contains predefined services that people can use out-of-the-box if they want to:

	https://docs.jboss.org/jbpm/v6.0/repository/

	This repository contains some integrations for common services like Twitter integration or file system operations that you can import.
	Simply point the import wizard to this URL to start browsing the repository.

	If you have an implementation of a common service that you would like to contribute to the community, do not hesitate to contact someone from the development team.
	We are always looking for contributions to extend our repository.

	== Setting up your own service repository

	You can set up your own service repository and add your own services by creating a configuration file that contains the necessary information (this is an extended version of the normal work definition configuration file as described earlier in this chapter) and putting the necessary files (like an icon, dependencies, documentation, etc.) in the right folders.

	The extended configuration file contains the normal properties (like name, parameters, results and icon), with some additional ones.
	For example, the following extended configuration file describes the Twitter integration service (as shown in the screencast above):

	[source]
	----
	import org.drools.core.process.core.datatype.impl.type.StringDataType;
	[
	[
	"name" : "Twitter",
	"description" : "Send a Twitter message",
	"parameters" : [
	"Message" : new StringDataType()
	],
	"displayName" : "Twitter",
	"eclipse:customEditor" : "org.drools.eclipse.flow.common.editor.editpart.work.SampleCustomEditor",
	"icon" : "twitter.gif",
	"category" : "Communication",
	"defaultHandler" : "org.jbpm.process.workitem.twitter.TwitterHandler",
	"documentation" : "index.html",
	"dependencies" : [
	"file:./lib/jbpm-twitter.jar",
	"file:./lib/twitter4j-core-2.2.2.jar"
	]
	]
	]
	----


	* The name property is the unique name for your service
	* The parameters property defines the service data inputs giving them a name and a type
	* You can similarly to input parameters also define the "results" property for service data ouputs (same structure applies)
	* The icon property should refer to a file with the given file name in the same folder as
	the extended configuration file (so it can be downloaded by the import wizard and used in the process
	diagrams). Icons should be 16x16 GIF files.
	* The category property defines the category this service should be placed under when
	browsing the repository.
	* The defaultHandler property defines the default handler implementation (i.e. the Java class that implements the `WorkItemHandler` interface and can be used to execute the service). This can automatically be registered as the handler for that service when importing the service from the repository. You can also use mvel to resolve the default handler expression which has the additional benefit of being able to resolve the handlers parameters, for example:
	[source]
	----
	"defaultHandler" : "mvel: new org.jbpm.process.workitem.twitter.TwitterHandler(ksession)",
	----
	Some of the available named parameters you can use are:
	[source]
	----
	ksession
	taskService
	runtimeManager
	classLoader
	entityManagerFactory
	----
	* The documentation property defines a documentation file that describes what the service does and how it works. This property should refer to a HTML file with the given name in the same folder as the extended configuration file (so it can be shown by the import wizard when browsing the repository).
	* The dependencies property defines additional dependencies that are necessary to execute this service. This usually includes the handler implementation JAR, but could also include additional external dependencies. These dependencies should also be located on the repository on the given location (relative to the folder where the extended configuration file is located), so they can be downloaded by the import wizard when importing the service. If the necessary dependencies are located in a maven repository you can define them via the mavenDependencies property, for example:
	[source]
	----
	"mavenDependencies" : [
	"org.jbpm:jbpm-twitter:1.0",
	"org.twitter4j:twitter4j-core:2.2.2"
	]
	----

	The root of your repository should also contain an [path]_index.conf_ file that references all the folders that should be processed when searching for services on the repository. This file could look as follows:
	[source]
	----
	Email
	FileSystem
	ESB
	FTP
	Google
	Java
	Jabber
	Rest
	RSS
	Transform
	Twitter
	----

	Each of those folders should then contain:

	* An extended configuration file with the same name as the folder (e.g. [path]_Twitter.conf_)
	that defines the service task
	* The icon as referenced in the configuration file
	* The documentation as referenced in the configuration file
	* The dependencies as referenced in the configuration file (for example in a lib folder)
	You can create your own hierarchical structure, because if one of those folders also contains an [path]_index.conf_ file, that will be used to scan additional sub-folders.
	Note that the hierarchical structure of the repository is not shown when browsing the repository using the import wizard, as the category property in the configuration file is used for that.

	== Programatically interacting with the service repository
	jBPM provides classes in the org.jbpm.process.workitem package which allows you to connect and retrieve your service information. For example:
	[source]
	----
	Map<String, WorkDefinitionImpl> workitemsFromRepo =
	WorkItemRepository.getWorkDefinitions("https://docs.jboss.org/jbpm/v6.0/repository/");
	----
	This will provide you with all services defined in the repository (and declared in your index.conf file). You can then get more detailed information about each of services in the repository using their name as declared in the service wid file, for example when using the twitter wid configuration from above we could do:
	[source]
	----
	workitemsFromRepo.get( "Twitter" ).getName(); // "Twitter"
	workitemsFromRepo.get( "Twitter" ).getDescription(); // "Send a Twitter message"
	workitemsFromRepo.get( "Twitter" ).getDefaultHandler(); // "org.jbpm.process.workitem.twitter.TwitterHandler"
	workitemsFromRepo.get( "Twitter" ).getDependencies(); // String["file:./lib/jbpm-twitter.jar","file:./lib/twitter4j-core-2.2.2.jar"]
	...
	----
	or you could for example check if the correct version of the service you need is contained in the repository:
	[source]
	----
	if( workitemsFromRepo.containsKey( "Twitter" ) && workitemsFromRepo.get( "Twitter" ).getVersion().equals( "1.0" )) {
	// do something
	}
	----
	Currently all operations are read-only. There isn't a way to update the service repository automatically.

	== Defining extended service configuration with JSON
	The previous extended configuration example for the Twitter service was defined with the default mvel configuration. It is also possible to do this with JSON and the Twitter example would look like this:
	[source]
	----
	[
	[
	"java.util.HashMap",
	{
	"name":"TestServiceFour",
	"displayName":"Twitter",
	"description":"Send a Twitter message",
	"parameters":[
	"java.util.HashMap",
	{
	"Message":["org.drools.core.process.core.datatype.impl.type.StringDataType", {}]
	}
	],
	"eclipse:customEditor":"org.drools.eclipse.flow.common.editor.editpart.work.SampleCustomEditor",
	"defaultHandler" : "org.jbpm.process.workitem.twitter.TwitterHandler",
	"documentation" : "index.html",
	"dependencies":[
	"java.util.ArrayList", ["file:./lib/jbpm-twitter.jar", "file:./lib/twitter4j-core-2.2.2.jar"]
	]
	}
	]
	]
	----
	In your service repository you can define the extended configuration of your services with mvel or JSON (or have some defined in one way and some in the other as well).
	Defining the extended configuration with JSON might have some benefits if being read by custom web-based clients for example.

	== Installing services from the service repository
	The Workbench provides two ways of installing services from the user defined service repositories:

	* Automatic install - allows you to specify the repository URL and a list of services (via their unique names specified in the wid) that will get installed and be ready for use when
	you create/open a business process in the Workbench. For example let's say we have a service repository available at http://mysite.com/myservicerepo and there we define as previsously mentioned two services, namely BuyStock and SellStock.
	To have these services automatically installed in the Workbench you can add the following startup parameters:
	[source]
	----
	AS/bin/standalone.sh -Dorg.jbpm.service.repository=http://mysite.com/myservicerepo -Dorg.jbpm.service.servicetasknames=BuyStock,SellStock
	----

	Or if you wanted just the SellStock service installed:
	[source]
	----
	AS/bin/standalone.sh -Dorg.jbpm.service.repository=http://mysite.com/myservicerepo -Dorg.jbpm.service.servicetasknames=SellStock
	----

	Currently there is no install-all option available so service names must be individually specified.
	When creating a new or opening an existing business process then the Workbench will attempt to install the specified services from the provided repository URL.
	This will install the service wid configuration, the spcified icon (if there is one or if not the Workbench will provide a default one for it), the default handler will be added to the deployment descriptor of your Workbench project as well as the specified maven dependencies in the service configuration will be added to the Workbench project pom.xml file.
	Please note that currently there is no option to specify maven repositories via the service task configuration so they must be added via the Workbench in its POM Editor by the users.

	* Manual installation through the Workbench - allows users to install one or more services from the services through the Workbench. You can find detailed information on how to do that in the <<jBPMDesigner,Process Designer Chapter>>.