Call for suggestions

All,

We are looking to update documentation as well as capabilities around PRD's. I would like to ask the community to help us prioritize a couple of items. We are looking for input on PRD/Workflow best practices. For example, what have you done that caused problems, what approach do you take when developing new PRD's, what actions, calls, etc... do you find challenging? The goal for this first item is to document some real world best practice guidelines around PRD development. The second item is around common PRD's that we can agree upon for a dozen or more out of the box PRD templates. The most common ones are pretty straight forward so we are looking for feedback on PRD's that would benefit the overall community if we created them out of the box.

Thank you all in advance for your feedback,
Tom Burt
  • # Best practices: Workflow Loops

    You could create counters and loops in flowdata, but it seems wiser to
    start a 2nd (service) workflow with a list of (dummy) recipients that
    are spawned as separate workflow instances
  • # Best practices: Ajax Calls

    While the IDM API IDVault.execService() is documented, info is missing
    how such custom services are implemented.
    A standard and supported interface would be helpful
  • On 7/13/2018 11:04 AM, tburt wrote:
    >
    > All,
    >
    > We are looking to update documentation as well as capabilities around
    > PRD's. I would like to ask the community to help us prioritize a couple
    > of items. We are looking for input on PRD/Workflow best practices. For
    > example, what have you done that caused problems, what approach do you
    > take when developing new PRD's, what actions, calls, etc... do you find
    > challenging? The goal for this first item is to document some real world
    > best practice guidelines around PRD development. The second item is
    > around common PRD's that we can agree upon for a dozen or more out of
    > the box PRD templates. The most common ones are pretty straight forward
    > so we are looking for feedback on PRD's that would benefit the overall
    > community if we created them out of the box.


    Rob Rawson wrote some good content on PRD's and approaches to building
    them that might be helpfil to link in...

    The series link is:
    https://www.netiq.com/communities/cool-solutions/series/workflow-primer-2/





  • tburt;2484005 wrote:
    All,

    We are looking to update documentation as well as capabilities around PRD's. I would like to ask the community to help us prioritize a couple of items. We are looking for input on PRD/Workflow best practices. For example, what have you done that caused problems, what approach do you take when developing new PRD's, what actions, calls, etc... do you find challenging? The goal for this first item is to document some real world best practice guidelines around PRD development. The second item is around common PRD's that we can agree upon for a dozen or more out of the box PRD templates. The most common ones are pretty straight forward so we are looking for feedback on PRD's that would benefit the overall community if we created them out of the box.

    Thank you all in advance for your feedback,
    Tom Burt


    Syntax. Syntax. Syntax.

    The number of repeat forum answers around syntax is quite significant.... things like how to multivalue mail fields ("||"), dealing with the difference between string and cstring (not all of us are Java developers so don't know/understand the impacts of Java changes), dealing with get* calls and whether they're objects, arrays, or strings and best coding around making sure it works first time....etc
  • tburt;2484005 wrote:
    All,

    We are looking to update documentation as well as capabilities around PRD's. I would like to ask the community to help us prioritize a couple of items. We are looking for input on PRD/Workflow best practices. For example, what have you done that caused problems, what approach do you take when developing new PRD's, what actions, calls, etc... do you find challenging? The goal for this first item is to document some real world best practice guidelines around PRD development. The second item is around common PRD's that we can agree upon for a dozen or more out of the box PRD templates. The most common ones are pretty straight forward so we are looking for feedback on PRD's that would benefit the overall community if we created them out of the box.

    Thank you all in advance for your feedback,
    Tom Burt


    "Built in features" that simply don't work... Testing. I mean just test the **** product properly for what is documented and how it *should* work. For example, use the Start Workflow activity but have the Provisioning Request Defn to start as a dynamic value...unless it only has "string" inputs, then you're stuffed....and despite raising this in v4.5/v4.6, v4.7 still hasn't resolved the issue.

    If you look at the One Identity product, when it comes to workflows, they made basic config simple. You can just add a workflow activity and select from a list of predefined options (i.e. line manager, department head, etc) instead of having to actually code anything. Yes, there should still be flexibility, but there should also be simplification.

    Then there is the logging....with the way tomcat spews its info out to 'incorrect' files after a period of time, just makes it awkward to trace issues....."engine" log entries go to the first dated catalina.out.xxxx-xx-xx.log file rather than the "today" log file....logging of the Engine probably needs to be segregated from tomcat logging...

    ...then there's Designer....because of the complexity of PRDs, Designer needs to work properly as there is absolutely no alternate...and when it doesn't, it completely stops development.
  • Hi,
    small brain dump:


    • Debugging - How to debug a PRD. Development cycles could be hugh if you don't know how to debug
    • Events - Where to put JavaScript. IMHO you will fail if you spread your JS all over the form items. Use a single point of JS.
    • Administration - Use Workflows for administrive tasks. I have often have seen customers doing so. Good idea? Bad idea?
    • Which objects are useable at which location. Not always the ECMA script builder shows all functions/objects available which makes you wonder how to achieve your needs.
    • Running PRDs - What state are they in? Who did something? Sometimes it is hard to get some informations out of running PRDs. A list like "you are looking for ...? Then do ..." could be helpfully.
    • GUI - don't bother with the build in GUI framework (is it called juice?) - use jQuery GUI
    • jQuery - jQuery is already included / is not included? I still wonder about. If you needs are more complex then use jQuery. Tips how to work with the form items could be helpfully. How to access them?


    to be continued :)

    regards
    Daniel
  • On 7/13/2018 9:04 AM, tburt wrote:
    >
    > All,
    >
    > We are looking to update documentation as well as capabilities around
    > PRD's. I would like to ask the community to help us prioritize a couple
    > of items. We are looking for input on PRD/Workflow best practices. For
    > example, what have you done that caused problems, what approach do you
    > take when developing new PRD's, what actions, calls, etc... do you find
    > challenging? The goal for this first item is to document some real world
    > best practice guidelines around PRD development. The second item is
    > around common PRD's that we can agree upon for a dozen or more out of
    > the box PRD templates. The most common ones are pretty straight forward
    > so we are looking for feedback on PRD's that would benefit the overall
    > community if we created them out of the box.
    >
    > Thank you all in advance for your feedback,
    > Tom Burt
    >
    >


    My main challenges have always been:
    - IDVault.get() retrieves a single value from an object - NEED something
    to pull the whole thing at once for performance reasons.
    - inability to write back to objects from the forms
    - IDVault.globalQuery() does not support full LDAP filter syntax nor
    retrieving chosen DAL attributes - same performance impact as IDVault.get()

    Would love to be able to pull a PRD down to filesystem splitting it into
    its ECMA components without Designer to do linting and unit testing on
    code, like we do with other web frameworks. Make that capability
    bi-directional and we can add pre-processing and transpiling to the
    build pipeline making it really nice to work with.


    posted also on : https://github.com/fchierad/PRD

    RBPM Work flow development notes/suggestions
    Save every value into flow data first.

    If you compute a value - for a conditional activity, or for an
    addressee, or for anything - save it put it in flow data via a mapping
    activity before you use it.

    Reasoning: by having the values in flowdata first it is possible to
    follow the flow and behavior of a workflow without the need to
    re-calculate values after the fact. This is useful both when
    troubleshooting a work flow in production and when debugging a workflow
    you are developing.

    This is especially useful for GCVs - by saving it in flowdata first we
    can perform validation if the GCV.get() was successful and also know
    what value the work flow saw at the moment it was executed, allowing you
    to validate after the fact if the GCV value was incorrect or broken.

    Try not to overwrite (change) flow data values

    Rather, prefer to create new flow data nodes with any new values you need.

    For example, rather than putting a userâ€Tms GivenName SN into a flow
    data node, and then later putting the userâ€Tms FullName into that same
    node: put it in a new node. This way we can see how the whole workflow
    unfolded at any point in the future, without having to re-create the
    state at a previous workflow activity.

    This is especially important regarding the workflow's initial values fed
    into flowdata from the Start activity's request form. By having those
    values it is possible to review and even re-issue a workflow at some
    point in the future.

    Obviously this cannot always be avoided - Loops, incrementing counters
    and so forth - so use good judgement.

    If you need to delimit several values, use a serializer library (e.g. JSON)

    If you need to pass structured values around, avoid concatenating them
    with a string character. Instead use a library that will escape and
    parse them 100% correctly. This will avoid having to either strip or
    encode your delimiter when seen in the input data, as well as unexpected
    behaviors if you leave the input data un-encoded.

    Map Activity suggestions:

    To make your workflow more readable try to make your "Source Expression"
    short or even a single function call. For this to be possible build your
    functions into Overview > Global Scripts with meaningful names and
    detailed comments on function usage, parameters and expected return
    values. I tend to follow the jsdoc standard on function comments to be
    able to auto-generate documentation from source code comments using
    automated tools.

    To complement the above we should try to reuse functions as much as we
    can. One or few small, well-named, generic functions should meet most
    use cases. Function reuse across activities and workflows can save time
    and effort in the long run, as well as make the code easier to maintain
    and change.

    Try to group flowdata destinations under logical, hierarchical
    groupings. So instead of multiple flowdata.RESTWhatThisis entries do
    flowdata.REST/WhatThisis. Hierarchy helps both when coding and later
    when debugging the workflow, or even when exporting flowdata XML from
    the database for review.

    If you need a value more than once (especially as an intermediate
    value), refactor that code into a mapping activity prior to where you
    needed it. For example: If you have a mapping activity with 10 flow-data
    rows in it, and the ECMA script for all 10 of them begins with
    calculating some user-related information via substring matching and
    regex: take that repetitive logic out and put it in an earlier activity
    (DRY – Donâ€Tmt Repeat Yourself principle).

    Delay activities (also known as approval activites, when used to
    pause/wait a workflow)

    Use the timeout path as the default path.

    Addressee should be a custom account in eDirectory, preferably read from
    a GCV. Do not hard code a user if at all possible. Do not assign to the
    initiator, recipient or their managers to avoid cluttering their Work
    Dashboard. Provide a default fallback in case GCV.get() fails.

    The timeout value should be a parameter set in a flowdata section before
    the delay.

    Approval form should be simple and only be relevant if we allow early
    advancement via approval/denial. In that case these paths should pass by
    a log message to record that an early advancement (or cancellation)
    happened, and log by whom it happened. If no interation is allowed just
    create a form with a single field describing it is a wait/delay/pause
    activity and add an onload event to hide the buttons of said form.

    Activity ID recommendations

    Change the activity ID of activities that will be referenced in later
    code from their default Activity# value, to make your code more readable.

    Personal preference is to start the ID with a 3 or 4 letter abbreviation
    such as map, log, appr, cond, inte, rest, stat, and so on; followed by
    camel case short name to describe what it does. This way when referring
    back to them we can have expressions like apprFromManager.getAddressee()
    instead of Activity657.getAddressee().

    There is no need to change all activity IDs to meaningful names, just
    ones that will be referenced in later code.

    An added bonus of this approach is that when looking at the web server's
    log the Activity: portion of the trace will have something that should
    help you understand where in the flow that particular process is at,
    instead of a number that have no meaning by itself. Of course to realize
    this benefit at least approval and flow control activities (branch,
    merge, condition) would need to have to be renamed.

    Notes
    Retrieving a work flow's flowdata in IDM 4.5/4.6 is fairly simple. The
    information resides on the RBPM database, afdocument table, metaxml
    column. Each supported database will have its own command line tools we
    can use to automate the process.

    Assuming a standard Postgresql install as the RBPM database we can run
    the command:

    /opt/netiq/idm/apps/postgres/bin/psql -U postgres -d idmuserappdb -c
    "COPY (SELECT metaxml FROM afdocument WHERE requestid='largehexvalue')
    TO STDOUT" | sed -e 's/\\n//g' | xmllint --format - >
    /somefilepath/flowdata.xml
    where largehexvalue should be the workflow's request ID as seen in
    multiple places such as the web server's log, and look similar to this
    string: 4052f820a9db47cbace1a7fd82c88e90 somefilepath should be the path
    where you want to save your workflow's flowdata XML export. The sed and
    xmllint portions of the command simply pretty-format the returned XML
    with line breaks and indentation.

    ECMA execution order when a form loads on the browser

    Engine scripts run first, their output goes to catalina.out:

    engine: Overview > Global Scripts
    Globalscripts load top to bottom
    engine: Start > Pre Activity > [fieldname]
    Field scripts are NOT executed top to bottom. Not sure on the order,
    currently suspect it may be alphabetical by field name
    Form (in browser) scripts run next, their output go to the form's HTML
    or the browser's console.log:

    form: Overview > Global Scripts
    Globalscripts load top to bottom
    form: Form > Scripts > [script]
    Scripts execute top to bottom
    form: Form > Events > onload
    form: Form > Fields > [field] > HTML Content
    Fields are processed top to bottom
    Only String-HTML fields have the "HTML Content" property
    form: Form > Fields > [field] > onload
    form: Form > Fields > [field] > onchange
    Comments:

    Field events seem to trigger top to bottom based on their order in Designer;
    Field onload happens on any given field before onchange. Onchange does
    trigger once during form load, so plan for It;
    HTML Content ECMA script runs before the field events;
    onchange did not trigger at all on the HTML field despite being set.
    Other field types might have the same constraint.
  • I will second the call for debugging...in fact that's more than a documentation issue, we need to be able to single step through PRDs, especially if they are heavily event based.
    Optimization would be another
    Better and more up to date documentation of objects and methods
    Best practices with jQuery to customize the forms
    Do something about the subtle differences between form and workflow methods and the objects they return
    Create an IDVault.getObject() for workflow that does not return a different class depending on the different search result
    If there is a way for the IDVault, field, form and event object to be implicitly passed to a function rather than having to be explicilty passed as a parameter, code would be simpler and more people would use functions to simplify their code
    OK this is getting beyond documentation
    SET SOAPBOX=OFF
  • Thank you all for the valued suggestions. The focus in the responses seems to be on documenting best practices and some enhancements which I agree should be taken up on both counts and have included them in requirements. As always, we may not be able to achieve all that is suggested but they are none the less appreciated.

    One additional request is a suggestion around out of the box workflows that we should include. I want to expand to a common set of 10, or maybe 20, workflows that can be used out of the box or as templates for customers. Obviously we would want to target the most common workflow use cases such as;
    1. Single step approval
    2. Multiple approver
    3. Contractor onboarding
    etc...

    Please provide suggestions around some of the most common workflows you have been deploying at customers or in multiple environments.
  • tburt;2484388 wrote:
    Thank you all for the valued suggestions. The focus in the responses seems to be on documenting best practices and some enhancements which I agree should be taken up on both counts and have included them in requirements. As always, we may not be able to achieve all that is suggested but they are none the less appreciated.

    One additional request is a suggestion around out of the box workflows that we should include. I want to expand to a common set of 10, or maybe 20, workflows that can be used out of the box or as templates for customers. Obviously we would want to target the most common workflow use cases such as;
    1. Single step approval
    2. Multiple approver
    3. Contractor onboarding
    etc...

    Please provide suggestions around some of the most common workflows you have been deploying at customers or in multiple environments.


    Then duplicate approval types for Role/Resource workflows...