{"id":18687584,"url":"https://github.com/alfresco/alfresco-process-sdk","last_synced_at":"2026-03-19T05:54:46.233Z","repository":{"id":148012714,"uuid":"599795568","full_name":"Alfresco/alfresco-process-sdk","owner":"Alfresco","description":"SDK for development using the APA Process Runtime services","archived":false,"fork":false,"pushed_at":"2024-04-12T21:34:37.000Z","size":4309,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":35,"default_branch":"develop","last_synced_at":"2024-04-14T05:10:31.490Z","etag":null,"topics":["studio"],"latest_commit_sha":null,"homepage":null,"language":"Mustache","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Alfresco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-02-09T22:30:17.000Z","updated_at":"2024-08-27T08:01:35.555Z","dependencies_parsed_at":"2023-12-18T17:03:39.438Z","dependency_job_id":"90e57ae7-221b-4bef-b595-0aba348d8d01","html_url":"https://github.com/Alfresco/alfresco-process-sdk","commit_stats":null,"previous_names":[],"tags_count":2448,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfresco%2Falfresco-process-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfresco%2Falfresco-process-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfresco%2Falfresco-process-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfresco%2Falfresco-process-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Alfresco","download_url":"https://codeload.github.com/Alfresco/alfresco-process-sdk/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239545654,"owners_count":19656825,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["studio"],"created_at":"2024-11-07T10:33:23.936Z","updated_at":"2025-11-08T02:30:37.343Z","avatar_url":"https://github.com/Alfresco.png","language":"Mustache","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Welcome to the Alfresco Process SDK\n\n![Build Status](https://github.com/Alfresco/alfresco-process-sdk/actions/workflows/build.yml/badge.svg)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/335dc8e0ffc54eada8d4ac674131b666)](https://www.codacy.com?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=Alfresco/alfresco-process-sdk\u0026utm_campaign=Badge_Grade)\n\n![alfreso logo](./docs/images/alfresco.png)\n\n## What is Alfresco Process SDK?\n\nThe Alfresco Process SDK includes APIs and samples that allows developers to quickly build Java applications that integrate with APA.\n\nThis SDK provides functionality to connect to Cloud-based servers. APA version 7.x and above are supported.\n\nThe APIs contained within have been generated using [Swagger Codegen](https://swagger.io/tools/swagger-codegen) from the public API definitions.\n\n## What is included?\n\nThe Alfresco Process SDK consists of these parts:\n\n- The main API ([alfresco-apa-java-rest-api](alfresco-apa-java-rest-api)) allows applications to consume APA public REST APIs.\n- The [samples](samples) folder includes a sample application configured to use the SDK. This has a `docker-compose` file and scripts that allows you to build and run the application. See [README](samples/java-rest-api-clients/README.md) for more details.\n- [Common logic](alfresco-java-rest-api-common) for REST APIs (primarily for authentication)\n\n## Getting Started\n\n### Usage Notes\n\nIt's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issues.\n\n### Quick start\n\nThis section contains the steps required for using the SDK with Spring.\n\n#### Pre-Requisites\n\n- Java version 17 or higher\n- Maven version 3.3 or higher\n\n#### 1. Create a new Spring Boot application\n\n#### 2. Add these dependencies to your project's build file\n\n##### Maven\n\nFirst, add to the repositories the Alfresco public repository containing the artifacts:\n\n```xml\n\n\u003crepositories\u003e\n\n  \u003crepository\u003e\n    \u003cid\u003ealfresco-public\u003c/id\u003e\n    \u003curl\u003ehttps://artifacts.alfresco.com/nexus/content/groups/public\u003c/url\u003e\n  \u003c/repository\u003e\n\n\u003c/repositories\u003e\n```\n\nThen, add the dependency on the APA starter\n\n```xml\n\n\u003cdependencies\u003e\n\n  \u003c!-- APA Java REST APIs --\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003eorg.alfresco\u003c/groupId\u003e\n    \u003cartifactId\u003ealfresco-apa-java-rest-api-spring-boot-starter\u003c/artifactId\u003e\n    \u003cversion\u003e{version-number}\u003c/version\u003e\n  \u003c/dependency\u003e\n\n\u003c/dependencies\u003e\n```\n\n##### Gradle\n\nFirst, add to the repositories the Alfresco public repository containing the artifacts:\n\n```groovy\nrepositories {\n  maven {\n    url \"https://artifacts.alfresco.com/nexus/content/groups/public\"\n  }\n}\n```\n\nThen, add the dependency on the starter\n\n```groovy\ncompile \"org.alfresco:alfresco-apa-java-rest-api-spring-boot-starter:{version-number}\"\n```\n\n#### 3. Configure Authentication for the REST API\n\nIn your `application.yml` file you can configure settings related to the content service repository, authentication mechanism, and credentials for accessing the REST API:\n\n```yaml\ncontent:\n  service:\n    url: https://repository:8080\n    security:\n      basicAuth:\n        username: username-here\n        password: password-here\n```\n\nIf you are using OAuth2, you can use client-credential based authentication:\n\n```yaml\nspring\n  security:\n    oauth2:\n      client:\n        registration:\n          alfresco-rest-api:\n            provider: alfresco-identity-service\n            client-id: clientId\n            client-secret: clientSecret\n            authorization-grant-type: client_credentials\n        provider:\n          alfresco-identity-service:\n            token-uri: ${keycloak.auth-server-url}/auth/realms/${keycloak.realm}/protocol/openid-connect/token\n```\n\nOr OAuth2 password based authentication:\n\n```yaml\nspring:\n  security:\n    oauth2:\n      client:\n        registration:\n          alfresco-rest-api:\n            provider: alfresco-identity-service\n            client-id: clientId\n            client-secret: clientSecret\n            username: username-here\n            password: password-here\n            authorization-grant-type: password\n        provider:\n          alfresco-identity-service:\n            token-uri: ${keycloak.auth-server-url}/auth/realms/${keycloak.realm}/protocol/openid-connect/token\n```\n\nAdditionally, if you want to provide a custom authentication mechanism, you can enable the delegated external authentication:\n\n```yaml\ncontent:\n  service:\n    security:\n      delegated: true\n```\n\nAnd provide a bean that implements the interface `DelegatedAuthenticationProvider`.\n\n#### 4. Configure Other Settings\n\nHere are some settings you may need to configure in your Application configuration file before using the SDK\n\n```yaml\nkeycloak:\n  auth-server-url: http://example.com/auth}\n  principal-attribute: ${ACT_KEYCLOAK_PRINCIPAL_ATTRIBUTE:preferred-username}\n  public-client: ${ACT_KEYCLOAK_CLIENT:true}\n  realm: ${ACT_KEYCLOAK_REALM:springboot}\n  resource: ${ACT_KEYCLOAK_RESOURCE:activiti}\n  security-constraints:\n    - authRoles:\n        - ${ACT_KEYCLOAK_ROLES:user}\n      securityCollections:\n        - patterns:\n            - ${ACT_KEYCLOAK_PATTERNS:/v1/*}\n    - authRoles:\n        - ${admin-role-name}\n      securityCollections:\n        - patterns:\n            - /admin/*\n  ssl-required: ${ACT_KEYCLOAK_SSL_REQUIRED:none}\n\nactiviti:\n  service:\n    query:\n      url: https://example.com\n      path: /example-app/query\n    runtime:\n      url: https://example.com\n      path: /example-app/rb\n    form:\n      url: https://example.com\n      path: /example-app/form\n    audit:\n      url: https://example.com\n      path: /example-app/audit\n    deployment:\n      url: https://example.com\n      path: /deployment-service\n    modeling:\n      url: https://example.com\n      path: /modeling-service\n    process-storage:\n      url: https://example.com\n      path: /process-storage\n\nauthentication:\n  service:\n    url: ${AUTHENTICATION_RUNTIME_URL:http://example.com}\n    path: ${AUTHENTICATION_PATH:/alfresco/api/-default-/public/alfresco/versions/1}\n\nprocess:\n  service:\n    url: ${PROCESS_SERVICE_URL:http://example.com}\n    path: ${PROCESS_SERVICE_PATH:/alfresco/api/-default-/public/alfresco/versions/1}\n```\n\n#### 4. Consume the REST API\n\n- Add to your main Spring application\n\n  ```java\n  @EnableFeignClients(basePackages = {\"com.alfresco.core.handler\",\n                                      \"com.alfresco.activiti.handler\",\n                                      \"com.alfresco.search.handler\",\n                                      \"com.alfresco.auth.handler\"})\n  public class SampleApplication { }\n\n  ```\n\n- Copy the class in the folder config/FeignConfiguration.java in your project\n  In order to resolve the references in FeignConfiguration you will need the following `\u003cdependencies\u003e`\n\n  ```xml\n  \u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.activiti.cloud\u003c/groupId\u003e\n        \u003cartifactId\u003eactiviti-cloud-api-process-model-impl\u003c/artifactId\u003e\n        \u003cversion\u003eversion-here\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.activiti.cloud\u003c/groupId\u003e\n        \u003cartifactId\u003eactiviti-cloud-api-task-model-impl\u003c/artifactId\u003e\n        \u003cversion\u003eversion-here\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.activiti\u003c/groupId\u003e\n        \u003cartifactId\u003eactiviti-api-runtime-shared\u003c/artifactId\u003e\n        \u003cversion\u003eversion-here\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.fasterxml.jackson.core\u003c/groupId\u003e\n        \u003cartifactId\u003ejackson-core\u003c/artifactId\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.fasterxml.jackson.core\u003c/groupId\u003e\n        \u003cartifactId\u003ejackson-databind\u003c/artifactId\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.fasterxml.jackson.datatype\u003c/groupId\u003e\n        \u003cartifactId\u003ejackson-datatype-jsr310\u003c/artifactId\u003e\n    \u003c/dependency\u003e\n  \u003c/dependencies\u003e\n  ```\n\n- If you are using keycloak you must include also the following:\n\n  ```xml\n    \u003cdependencies\u003e\n      \u003cdependency\u003e\n        \u003cgroupId\u003eorg.activiti.cloud\u003c/groupId\u003e\n        \u003cartifactId\u003eactiviti-cloud-services-common-security\u003c/artifactId\u003e\n        \u003cversion\u003eversion-here\u003c/version\u003e\n      \u003c/dependency\u003e\n    \u003c/dependencies\u003e\n  ```\n\nTo see how classes within the SDK can be used to call APIs, refer to [this example](samples/java-rest-api-clients/src/main/java/org/alfresco/java/rest/client/sample/service/RESTClientService.java)\n\n### Usage in a non-spring application\n\nYou can check the documentation here:\n\u003chttps://github.com/OpenFeign/feign\u003e\n\n## Building the SDK\n\nIt is not necessary to build the SDK in order to use it. You can instead reference the released version of the sdk\nby following the instructions [above](#getting-started).\n\nIf you still intend to build it, follow these instructions:\n\n### Pre-Requisites\n\n- Java version 17 or higher\n- Maven version 3.3 or higher\n- An APA environment with a deployed application from which to fetch the API definitions\n\n### Build Steps\n\nIn order to build the SDK for the first time you will need access to a running APA environment.\nThis is necessary in order to retrieve the API definitions.\n\nYou can either set the necessary environment variables ahead of time, or include them with the build command.\n\nSetting in advance:\n\n```console\nMAVEN_CLI_OPTS=\"${MAVEN_CLI_OPTS} -Denvironment.host=your-installed-environment-host\"\nMAVEN_CLI_OPTS=\"${MAVEN_CLI_OPTS} -Denvironment.apa.host=your-installed-apa-environment-host\"\nMAVEN_CLI_OPTS=\"${MAVEN_CLI_OPTS} -Denvironment.application.name=your-deployed-APA-application-name\"\nMAVEN_CLI_OPTS=\"${MAVEN_CLI_OPTS} -U\"\nexport MAVEN_CLI_OPTS\n```\n\nIncluded on command line:\n\n```console\nmvn clean install -Denvironment.host=your-installed-environment-host -Denvironment.apa.host=your-installed-apa-environment-host -Denvironment.application.name=your-deployed-APA-application-name\n```\n\nThis will generate the source code for the APA REST API clients first, then it will compile all the modules and run the\ncorresponding unit and integration tests.\n\nIf you want to skip the generation of the REST API clients code, you can do so by setting the maven property `skip.generation`:\n\n```console\nmvn clean install -Dskip.generation\n```\n\nHowever, you must build the project at least once _without_ skipping the generation step in order to compile the SDK. From that point, you\ncan skip the generation step if unneeded.\n\n## License Management\n\nModules in this repo use the following Maven plugins to perform licensing related tasks:\n\n- [com.mycila:license-maven-plugin](https://mycila.carbou.me/license-maven-plugin/) is used for checking and updating the license header on all applicable files. This is typically done at the beginning of a new year.\n- [org.codehaus.mojo:license-maven-plugin](https://www.mojohaus.org/license-maven-plugin/) is used to manage third party licenses. Specifically generating a report of all licenses used by dependencies.\n\nSince these plugins have the same name (excluding the groupId), running them requires qualifiying the goal with the full name.\n\n### Updating the license header\n\nTo check that the license header is consistent across all source files, run this command:\n\n`mvn com.mycila:license-maven-plugin:check`\n\nIf any source files have a modified or missing license header, this goal will fail.\n\nTo fix the license header on all source files, run this command:\n\n`mvn com.mycila:license-maven-plugin:format`\n\nAny files that did not have the correct header will be reformatted and appear in your unstaged changes.\n\nYou can use this command to update the license header when the Copyright year should be updated. Before running the format goal, modify [pom.xml](pom.xml) with the current year:\n\n```xml\n\u003cproperties\u003e\n    \u003cproject.year\u003eyear-here\u003c/project.year\u003e\n\u003c/properties\u003e\n```\n\nSee the [plugin documentation](https://mycila.carbou.me/license-maven-plugin/) for all possible goals.\n\n### Listing Third Party Licenses\n\nTo list all third party licenses across all modules, the following command can be used:\n\n`mvn org.codehaus.mojo:license-maven-plugin:aggregate-third-party-report`\n\nThis will create a file located at `.\\target\\site\\aggregate-third-party-report.html`, which contains a list of the licenses for all dependencies for all modules.\n\nAdditionally, per-module text-based reports can be created with this command:\n\n`mvn org.codehaus.mojo:license-maven-plugin:add-third-party`\n\nFor each module a file will be created at `target\\generated-sources\\license\\THIRD-PARTY.txt`\n\nSee the [plugin documentation](https://www.mojohaus.org/license-maven-plugin/) for all possible goals.\n\n## CI/CD\n\nRunning on GH Actions.\n\nFor Dependabot PRs to be validated by CI, the label \"CI\" should be added to the PR.\n\nRequires the following variables to be set:\n\n| Name                 | Description                                                      |\n| -------------------- | ---------------------------------------------------------------- |\n| ENVIRONMENT_APA_HOST | URL of APA environment to use for SDK generation                 |\n| ENVIRONMENT_APP      | Name of the app within the environment to use for SDK generation |\n| ENVIRONMENT_HOST     | Base URL of environment to use for SDK generation                |\n\nRequires the following secrets to be set:\n\n| Name                         | Description                        |\n| ---------------------------- | ---------------------------------- |\n| BOT_GITHUB_TOKEN             | Token to launch other builds on GH |\n| BOT_GITHUB_USERNAME          | Username to issue propagation PRs  |\n| DOCKER_USERNAME              | Docker Hub repository username     |\n| DOCKER_PASSWORD              | Docker Hub repository password     |\n| NEXUS_USERNAME               | Internal Maven repository username |\n| NEXUS_PASSWORD               | Internal Maven repository password |\n| QUAY_USERNAME                | Quay.io docker registry username   |\n| QUAY_PASSWORD                | Quay.io docker registry password   |\n| SLACK_NOTIFICATION_BOT_TOKEN | Token to notify slack on failure   |\n\n## Release process\n\nThe release process is partially automated using the [release workflow](.github/workflows/release.yml).\nThis workflow creates a release branch, updates the version in the `pom.xml` files, and creates a PR for the release branch.\n\nTo create a release, follow these steps:\n\n1. Run workflow mentioned above.\n2. Add any label into generated PR to trigger check run.\n3. Merge the PR if no issues are found.\n4. Check if new github release and tag is created.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falfresco%2Falfresco-process-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falfresco%2Falfresco-process-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falfresco%2Falfresco-process-sdk/lists"}