app 4.1 Community Edition Documentation

app 4.1 Community Edition Documentation

Overview

app is an open source, workflow management software suite, which includes tools to automate your workflow, design forms, create documents, assign roles and users, create routing rules, and map an individual process quickly and easily. It's relatively lightweight and doesn't require any kind of installation on the client computer. This file describes the requirements and installation steps for the server.

Development

System Requirements

You can develop app as well as app packages locally. In order to do so, you must have the following:

• Virtualbox 5.2 or above
• Vagrant 2.2.0 or above
• PHP 7.2.0 or above
  • Windows users can install XAMPP
• Composer
• Node.js 10.13.0 or above

Steps for Development Installation

• Clone the repository into a directory
• Perform composer install to install required libraries. If you are on windows, you may need to run composer install --ignore-platform-reqs due to Horizon requiring the pcntl extension. You can safely ignore this as the application runs in the virtual machine which has the appropriate extensions installed.
• Perform npm install in the project directory
• Perform npm run dev to build the front-end assets
• Modify your local /etc/hosts file to point bpm4.local.processmaker.com to 192.168.10.10. On Windows, this file is located at C:\Windows\System32\Drivers\etc\hosts.
  • If you need to change the ip address to something else to avoid conflicts on your network, modify the Homestead.yaml file accordingly. Do not commit this change to the repository.
• Execute vagrant up in the project directory to bring up the laravel homestead virtual machine
• Execute vagrant ssh to ssh into the newly created virtual machine
• Execute php artisan bpm:install in /home/vagrant/processmaker to start the app Installation
  • Specify localhost as your local database server
  • Specify 3306 as your local database port
  • Specify workflow as your local database name
  • Specify homestead as your local database username
  • Specify secret as your local database password
  • Specify https://bpm4.local.processmaker.com as your application url
• Visit https://bpm4.local.processmaker.com in your browser to access the application
  • Login with the username of admin and password of admin

When developing, make sure to turn on debugging in your .env so you can see the actual error instead of the Whoops page.

APP_DEBUG=TRUE

Optionally, trust the self-signed certificate on your host machine so you don't get the "Not Secure" warnings in chrome and postman.

For OSX: 1. In your-repository-root/storage/ssl, double-click on bpm4.local.processmaker.com.crt 1. Click on "Add" to add it to your login keychain 1. In the Keychain Access window click on the Certificates category on the bottom left. 1. Double-click on the bpm4 certificate 1. Open the Trust section. For "When using this certificate", select "always trust" 1. Close the window. You will be asked for your password. Close and reopen the processmaker tab in chrome.

API

The app API is documented using OpenAPI 3.0 documentation and can be viewed at /api/documentation. The documention is generated by adding annotations to Models and Controllers.

All api endpoints should be well annotated because it's how we generate the SDKs that are used when running scripts.

When developing, make sure to add this to your .env file so that any changes you make to the annotations are automatically turned into documentation when you reload the /api/documentation page:

L5_SWAGGER_GENERATE_ALWAYS=TRUE

At the comment block at the top of the model, add an @OA annotation to describe the schema. See app/Models/Process.php for an example.

To keep things dry, you can define 2 schemas. One that inherits the other.

/**
 * ...existing comments above...
 * 
 * @OA\Schema(
 *   schema="ProcessEditable",
 *   @OA\Property(property="process_category_uuid", type="string", format="uuid"),
 *   @OA\Property(property="name", type="string"),
 *   @OA\Property(property="description", type="string"),
 *   @OA\Property(property="status", type="string", enum={"ACTIVE", "INACTIVE"}),
 * ),
 * @OA\Schema(
 *   schema="Process",
 *   allOf={@OA\Schema(ref="#/components/schemas/ProcessEditable")},
 *   @OA\Property(property="user_uuid", type="string", format="uuid"),
 *   @OA\Property(property="uuid", type="string", format="uuid"),
 *   @OA\Property(property="created_at", type="string", format="date-time"),
 *   @OA\Property(property="updated_at", type="string", format="date-time"),
 * )
 */
class Process extends Model implements HasMedia
{
...

Now you can use the reference to the schema when annotating the controllers. See app/Http/Controllers/Api/ProcessController.php for an example.

    /**
     * @OA\Get(
     *     path="/processes",
     *     summary="Returns all processes that the user has access to",
     *     operationId="getProcesses",
     *     tags={"Process"},
     *     @OA\Parameter(ref="#/components/parameters/filter"),
     *     @OA\Parameter(ref="#/components/parameters/order_by"),
     *     @OA\Parameter(ref="#/components/parameters/order_direction"),
     *     @OA\Parameter(ref="#/components/parameters/per_page"),
     *     @OA\Parameter(ref="#/components/parameters/"),
     * 
     *     @OA\Response(
     *         response=200,
     *         description="list of processes",
     *         @OA\JsonContent(
     *             type="object",
     *             @OA\Property(
     *                 property="data",
     *                 type="array",
     *                 @OA\Items(ref="#/components/schemas/Process"),
     *             ),
     *             @OA\Property(
     *                 property="meta",
     *                 type="object",
     *                 allOf={@OA\Schema(ref="#/components/schemas/metadata")},
     *             ),
     *         ),
     *     ),
     * )
     */
    public function index(Request $request)
    {
    ...

And for a show method

    /**
     * @OA\Get(
     *     path="/processes/{processUuid}",
     *     summary="Get single process by ID",
     *     operationId="getProcessByUuid",
     *     tags={"Process"},
     *     @OA\Parameter(
     *         description="ID of process to return",
     *         in="path",
     *         name="processUuid",
     *         required=true,
     *         @OA\Schema(
     *           type="string",
     *         )
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="Successfully found the process",
     *         @OA\JsonContent(ref="#/components/schemas/Process")
     *     ),
     */
    public function show(Request $request, Process $process)
    {
    ...

Notes

operationId will be the method name of the generated code. It can be anything camel cased but should be named some intuitive.

Testing with Swagger UI

Reload the swagger UI at api/documentation page in your browser to see the results and debug any errors with the annotations.

All api requests are authenticated with laravel passport oauth2. You need to generate a swagger ui client for your current logged in user.

First, get your user's uuid in text format.

$ php artisan tinker
>>> User::first()->uuid_text

Copy the UUID that looks like 1eaee1f0-cd80-11e8-9feb-0242cdbcf107

Then use php artisan to create the client

php artisan passport:client

It will ask you several questions. For Which user ID should the client be assigned to? enter the uuid you got before. For What should we name the client? enter swagger-ui and for Where should we redirect enter your app's url with the path /api/oauth2-callback, for example https://bpm4.processmaker.local/api/oauth2-callback (don't forget to match http and https)

Copy the resulting client id and client secret. Then in the swagger UI click on Authorize and enter the client id and secret. You should now be able to use the "Try it out" functionality.

You can add SWAGGER_CLIENT_ID and SWAGGER_CLIENT_SECRET to your .env so you don't have to keep entering it.

More Info

Detailed examples can be found at https://github.com/zircote/swagger-php/tree/master/Examples/petstore.swagger.io

Full OpenAPI 3.0 specification at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md

License

app - Automate your Workflow Copyright (C) 2002 - 2018 app Inc.

For further information visit: http://www.processmaker.com/