Package: ax
Ax - Makes workflow automation less annoyingThe Ax is software for rapid workflow automation.
If you are still using spreadsheets and email to manage your work, use Ax to automate it!What is AxThe Ax is a software for building and running workflow applications.It is a python program distributed by PyPi package manager.It is self-hosted and uses super-fast Sanic frameworkHow does it workCreate a form with a constructor.Form records have a lifecycle that is defined by a set of states.States are connected with each other with "Actions" forming a Finite State Machine.Users can have different field permissions for each state.When "Action" is performed and record state is changed an arbitrary python code is executed.This can be used to send emails, call APIs, move robots, launch rockets, etc.Use casesWorkflow automationExample - Facility Access Request, RFC request, Estimation queries, Asset Purchase, New Hire Request, Time Off Request, Purchase Request, Job Offer, etcContent management[Headless CMS]CRMECMHelpDeskExpert systemsEducational coursesAx is currently in BETASpecial offer for first usersAx team offersFREEconsulting services for users with paid support plan.If you want to automate any workflow - pleasecontact the teamdescribing the task. We will configure a VPS with Ax workflow, build a workflow app you need and teach you how to use it.DocumentationAx workflow documentation is separated into four levels of complexity:Getting startedBeginnerAdvancedHackerInstall AxRun AxCreate formCreate gridPermissionsRelation fieldsWorkflowPage designerManage usersMarketplaceActionsQuery constructorDynamic rolesAx ConfigurationRunning in productionApp packageCloud platformsWeb-componentsGraphql APIComplex workflowAdvanced appsGetting startedInstall AxThe Ax is a python application available as apypipackage.
You can install and run Ax in1 minute. No configuration is required.
All you need is to run this simple command to installAx:pip3 install axPython 3.6andPyPI packet managerare required.Complete installation guide with videos:UbuntuCentOsWindowsRun AxTo start Ax server on localhost (127.0.0.1:80) simply run the command:axOr specify host and port:ax --host=192.168.0.16 --port=8080You will see this message:Follow the URL and Use default administrator credentials to enter the Admin console:email:default@ax-workflow.compassword: deletemeWith no configuration, the Ax uses built-inSanicwebserver,SQLiteas database andRAMfor storing cache.If you expect a heavy load, you can configure Ax to useGunicornweb-server,Postgre SQLandRedis.ВThe Ax is built on top ofSanic, the super-fast python framework.Taking aВ tourThe tour is available for each page of the Admin console. Press thelife-ring iconat the right of the toolbar to start a tour.Basic usageThe basic usage of Ax consists of these steps:Create a formCreate a gridSet permissionsSend links to usersCreate aВ formClick or drag-n-drop field on the left drawer to add it to the form.Create aВ gridClick or drag-n-drop form field on the left drawer to add it to the grid.Set workflow permissionsConfiguring workflow is optional. If you are building something like a simple survey, you can stick with the default workflow.It consists of a single stateвЂЉ-вЂЉ"Created" and three actionsвЂЉ-вЂЉ"Add record", "Update", "Delete record".The default workflow does not contain any user roles. So initially only administrators can create and view records.In order to give your users the ability to use form and grid, you have to:Create a new roleAssign a role to States and actions by drag-n-dropAdd users to the roleSet field permissions for each stateNote: Two technical user groups are availableвЂЉ-вЂЉAll Users and EveryoneSend linksNow you can send users a link to form or grid.There is"Copy form URL"and"Copy grid URL"buttons available at the form and grid constructors.There are more advanced options for representing workflow applications to end-users. Please read Pages Designer, Using web-components, Using GraphQL APIBeginnerRelation fieldsAx starts to shine when you are dealing with complex applications with dozens of interconnected forms. The forms can be connected with reference fields. Currently, there are 3 types of reference field types available:1to1вЂЉ-вЂЉSimplest relationship. One record is connected to one record of another form.ВExample: Country в†’ Capital city. The country can have only one capital.The text and icon of reference chips can be configured in form settings.Set form reference label to {{name}} in order to user "name" fields value for chips. By default, the row GUID is used for chips.1toMвЂЉ-вЂЉOne record is referencing multiple records.ВExample: Country в†’ Cities. The country can have many cities.1toM Table viewвЂЉ-вЂЉSame as 1toM but looks like a table and allows the creation of new records.SimpleВ WorkflowEvery form record in Ax has a "State" attribute. Form states are shown as rounded rectangles.Users change state of a record by performing "Actions". Actions are shown as arrows from one state to another.Example: Action "Create record" of default workflow creates record and changes state to "Created"Steps needed for creating a workflow:Create statesCreates actions between statesCreate workflow rolesAssign roles to states and actions by drag-n-dropAssign users to rolesSet fields permissions for each stateDefault workflowBy default, the workflow has only one state"Created"and three actionsвЂЉ-вЂЉ**"Create record"**,"Update"and"Delete"There are three technical states:StartвЂЉ-вЂЉActions from the Start state are creating new records. The Start state means that the record does not yet exist. Start actions are available in grids. You can modify field permissions for Start state.DeletedвЂЉ-вЂЉActions to the Deleted state are deleting records from the database.AllвЂЉ-вЂЉActions from the All state are available on all states.Custom statesTo create a new State you must double-click on an empty spot in workflow constructor.Drag states to change there location.Hold mouse over State and press "Del" on the keyboard to delete it.Click on the State to change field permissions, rename it or to delete it.Custom actionsTo create new action you need to click on a state, hold the mouse button for 0,5 sec, then drag to another state to create an Action.ВWhile creating new action you can drag it to the same state to create "Self-action" (like the default "Update" action). Self actions do not change state, but form values are updated.Hold and drag the name of created action to make the line curved. Useful for visually organizing actions in the workflow.Hold mouse over action name and press the "Del" button on the keyboard to delete it.Click on the action name to open settings.Available settings are:Action nameвЂЉ-вЂЉLabel of a button that displayed to usersAction code nameвЂЉ-вЂЉAx allows you to call form Actions from enother form actions using python code. In order to do so, you must specify a code-name. Additionally, actions can be called as GraphQL mutations. The name of the mutation is the same as code-name.Roles that can perform the actionвЂЉ-вЂЉA list of workflow roles that can perform this action.Actions python codeвЂЉ-вЂЉCustom python code to be executed when action is performed. More info in advanced docs.Confirmation textвЂЉ-вЂЉIf this field is not empty the user will be prompted the confirmation when he clicks the action button. Default "Delete" action has confirmation text.Close modal on actionвЂЉ-вЂЉIf enabled the form will be closed after an action is performed. (Only works if the form was opened from the grid)PagesВ designerThere are several way to present grids and forms to your users. The simplest is to send link to a specific form. But if you are building a complex app with dozen inter-connected forms, then you need a custom interface. Ax pages can help you out.Ax Pages is a stand-alone web-application for end-users of Ax workflow apps. Basically it is a collection of HTML pages with tree-like navigation. Ax Pages comforts progressive web application requirements, so it can be installed as an application on android and ios phones.You create page using Markdown or HTMLВInsert<ax-grid form='SomeFormDbName' grid='SomeGridDbName' />tag in page to display a ax grid. SomeFormDbName and SomeGridDbName are database names of form and grid. You can skip the grid attribute if you want a default grid.Insert<ax-form db_name='SomeFormDbName' row_guid='someGuid' />tag in page to display form of certain record. Skip row_guid attribute if you want to create new records. You can use AxNum field values as a row_guid. Check the AxNum field type hint for more info.Pages are avalible as root of the host.http://127.0.0.1:8080/admin/home- Admin consolehttp://127.0.0.1:8080- Ax PagesUsing MarketplaceApplications can be installed either from GitHub repo or by uploading a package file. Also, the marketplace has a curated list of workflow applications that you can search and install.Click on the application repo link to know more about workflow application. Read the description of forms and workflows. Check Github starts and issues. Check source code.Beta Note: Reload page if the app folder does not appear after the install is complete.Manage users"Manage users" page allows you to create and modify Ax users and groups.ВThe Ax user is defined only by email and a short name.ВIf you need more data about users (full name, department, etc), please create Ax Form for that and link it to the user.AdvancedAdvanced WorkflowвЂЉ-вЂЉActionsAx allows to run a custom python code while performing workflow actions. Form and user data is available inside the python code.ВHere are some examples of how code can be used:Send emails with form dataCheck form values and abort actions if certain conditions are not metCalculate field valuesPerform actions on other records or even other formsGenerate documentsвЂЉ-вЂЉpdf, word, excelScrap information from external web-sitesExecute custom SQL query on dataCall external APIsWhile performing the action code, you can use these predefined properties:ax.row.guidвЂЉ-вЂЉGUID of the current record**ax.row.<field_name>**вЂЉ-вЂЉFor data on any field of the current record. Note that changing this property value will change value of the field.ax.argumentsвЂЉ-вЂЉ Dict of arguments. Used if action is called from another actionax.stripeвЂЉ-вЂЉSee AxPaymentStripe documentation for more infoax.user_emailвЂЉ-вЂЉemail of current userax.user_guidвЂЉ-вЂЉGUID of the current userax.tom_labelвЂЉ-вЂЉReference label of the current recordax.hostвЂЉ-вЂЉHost of Ax server. Taken from app.yamlax.form_urlвЂЉ-вЂЉUrl of the current recordax.formвЂЉ-вЂЉCurrent forms dataвЂЉ-вЂЉname, database name, icon, fields list, grids list etc.ax.action= Data of currenlty performing actionвЂЉ-вЂЉname, code name, from state, to state etc.ax.paths.uploadsвЂЉ-вЂЉOS directory for file uploadsax.paths.tmpвЂЉ-вЂЉOS directory for temporary file uploadsax.modal_guid= GUID of a modal window that was used to run actionAlso, you can use these handy methods:ax.emailвЂЉ-вЂЉsends email (SMTP must be configured)awaitax.email(to='info@ax-workflow.com',text='Hello ax',html='Hello <b>ax</b>',subject='Sample email')ax.sqlвЂЉ-вЂЉExecute custom SQL commandsql='UPDATE "Stock" SET "axState"=\'Confirmed\'WHERE "sourceCatalog"=:load_guid'params={"load_guid":ax.row.guid}ax.sql(sql,params)ax.printвЂЉ-вЂЉAsync action that opens a terminal window and shows a message to user. Useful for debugging and for long-lasting actions. If your action takes 5 minutes to execute, you can use ax.print to notify the user on progress.ax.print('Hello world')ax.do_actionвЂЉ-вЂЉExecute another Ax actionforidx,stockinenumerate(drafts):ax.print(f'\nрџ“¦{idx}')awaitax.do_action(form_db_name='Stock',action_db_name='findWineAsync',row_guid=stock['guid'],modal_guid=ax.modal_guid,values=None,arguments={"aiohttp_session":session})ax.add_action_jobвЂЉ-вЂЉAdd scheduler job (Work in progress)In addition, you can set these output properties:ax.message-String property. Outputs a message modal when action is finished.ax.errorвЂЉ-вЂЉString property. Outputs an error modal when action is finished.ax.abortвЂЉ-вЂЉBoolean property. If set to trueвЂЉ-вЂЉthe record will not change state after performing action. Useful when you want to check field values inside actions python code.Advanced GridвЂЉ-вЂЉQuery constructorAx allows you to construct custom SQL queries for grids. Press the "Query constructor" button on "Grids" page to open modal.Here is the default value for a grid:ax.query=f"""SELECT{ax.db_fields}FROM "{ax.db_table}";"""As you can see, it is a python code that is executed before SQL query.you can use these predefined properties:ax.db_fieldsвЂЉ-вЂЉString that contains all grid fields. Used in the default SQL query.ax.db_tableвЂЉ-вЂЉGrid database name. Same as a database table.ax.argumentsвЂЉ-вЂЉDict of arguments. Used if when the grid is used as web-component.ax.user_emailвЂЉ-вЂЉemail of current userax.user_guidвЂЉ-вЂЉGUID of the current userax.formвЂЉ-вЂЉCurrent forms dataвЂЉ-вЂЉname, database name, icon, fields list, grids list etc.ax.gridвЂЉ-вЂЉ Data of the current grid.Example usage:If you want a grid that shows only records created by current User, you have to use an  Author field and this grid query:ax.query=f"""SELECT{ax.db_fields}FROM "{ax.db_table}"WHERE "author"='{ax.user_email}';"""Advanced WorkflowвЂЉ-вЂЉDynamicВ rolesSometimes you want to give user permissions based on values of the record. (ExampleвЂЉ-вЂЉonly the author can modify the record) For this purpose, you can create a dynamic role.ВThe dynamic role is a custom python code that is executed before displaying the form.ВWARNING:These roles are working only for form view. Not working for grids.The default code for dynamic role is:ax.result=Falseif(ax.row.some_field==ax.user_email):ax.result=Trueax.resultвЂЉ-вЂЉIs a boolean output property that is used to determine if the current user fits dynamic role.These pre-defined properties are available:ax.row.guidвЂЉ-вЂЉGUID of the current record**ax.row.<field_name>**вЂЉ-вЂЉFor data on any field of the current record. Note that changing this property value will change the value of the field.ax.user_emailвЂЉ-вЂЉemail of current userax.user_guidвЂЉ-вЂЉGUID of the current userax.hostвЂЉ-вЂЉHost of Ax server. Taken from app.yamlAx ConfigurationYou can configure Ax by editing app.yaml file at the installation folder.To determine folder location run pip command:pip show axAll available settings are already present in theapp.yamlfile but are commented.
Here are the list of what you can configure:Logging settingsвЂЉ-вЂЉSet log level. Set a logfile name if you want to save logs to file. Set directory if you want to save logs to specific place.Internalization settingsвЂЉ-вЂЉSet timezone and language (Only English is available at a time)Sanic server settingsвЂЉ-вЂЉSet host and port of web-server. Set number of workers. The number of workers cant be bigger than your CPU cores. Only 1 worker available for MS Windows machinesDatabase settingsвЂЉ-вЂЉBy default Ax uses SQLite database. The database file is ax_sqlite.db which is located in the installation folder. For better performance, Ax can use the PostgreSQL database.Upload settingsвЂЉ-вЂЉSet custom upload folder.ВEmail settingsвЂЉ-вЂЉSet SMTP settings to be usedSSL SettingsвЂЉ-вЂЉ SSL settings for Sanic web-serverField types settingsвЂЉ-вЂЉCurrently there are only Stripe payment field settingsRunning in productionWe recommend running ax usingMonit daemon. It will restart ax if it freezes of crashes (Ax is in Beta, remember?)Check guid for more info:Setting Monit for Ax on UbuntuCreating a marketplace appAx application is a collection of forms and pages that can be installed on any Ax instance using a package zip file or GitHub repo. (The zip file is actually just an archive of a repo).Simple steps to create an app:Create a form folderGroup all forms that you want to save inside created folderGroup all pages that you want to save under one root pageOpen folder setting and click "Create app"You will be asked:Code nameвЂЉ-вЂЉthe name of archiveApplication root pageвЂЉ-вЂЉthe code name of the page you used to group all application pages.Create Readme.md from root pageвЂЉ-вЂЉSet this option if your want to generate readme.md file. Useful for publishing to GitHub.Save form data?вЂЉ-вЂЉSet this option if you want to save the data of your forms, not just structure.HackerUsing Ax on cloud platformsUsing web-componentsUsing graphql APIComplex workflow featuresAdvanced Marketplace applications