Activity parameters

format

Default is csv using delimiter to create lines. If set to json, the result is encoded using JSON with the keys title, head and data. Set to memory to retrieve the data portion of the report directly in the context value defined by target_key.

target_key

Write the report data into the workflow context using this key. The filesystem is not used in this case, so all file related settings are ignored.

If the format is set to memory the default value is _report_data.

target_filename

Filename to write the report to, if relative (no slash), target_dir must be set and will be prepended. If not given, a random filename is set.

target_dir

Mandatory if target_filename is relative or not set.

target_overwrite

boolean, overwrite the target file if it exists.

target_umask

The umask to set on the generated file, default is 640. Note that the owner is the user/group running the socket, if you want to download this file using the webserver, make sure that either the webserver has permissions on the daemons group or set the umask to 644.

delimiter

A single char which is used as delimiter. Default is the pipe symbol |. Be aware that no escaping or quoting of values is done, so you can only use a symbol that will not occur in the data fields! Good choices beside the pipe is a tab (\t), semicolon (;) or hash (#);

head

A string or template toolkit pattern to put into the first line of the report file. If not set, a default header is added. Available template vars are (both dates are in ISO8601 format):

include_expired

Parseable OpenXPKI::Datetime value (autodetected), certificates which are expired after the given date are included in the report. Default is not to include expired certificates.

include_revoked

If set to a true value, certificates which are not in ISSUED state (revoked, crl pending, on hold) are also included in the report. Default is to show only issued certificates.

valid_at

Parseable OpenXPKI::Datetime value (autodetected) used as base for validity calculation. Default is now.

cutoff_notbefore

Parseable OpenXPKI::Datetime value (autodetected), show only certificates where notebefore is between valid_at and this value.

cutoff_notafter

Parseable OpenXPKI::Datetime value (autodetected), show certificates where notafter is less then value. The requested valid_at or, if set, the expiry cutoff date is added as lower border.

unique_subject

If set to a true value, only the certiticate with the latest notbefore date for each subject is included in the report. Note that filtering on subject is done AFTER the other filters, e.g. in case you do not include revoked certifiates you get the latest one that was not revoked. Subjects are compared case insensitive!

aggregate

Pass the name of a column you want to aggregate the result on. This will turn off the default columns and append the rowcount per line as the last column.

subject

Expression to use as filter on the subject of the certificate. This is passed with a "like" operator to the sql layer, the asterisk can be used as wildcard. Mutiple expressions are possible and or'ed together.

profile

Only include certificates with this profile in the report, mutliple profiles can be passed as list.

subject_alt_name

Filter certificates having a certain subject_alt_name set, can be a scalar with SQL wildcards OR a list of items.

meta_*, system_*

Lets you search for any certificate attribute having a listed prefix. You can set the special value <undef> (including the angle brackets) to search for rows without a certain attribute.

report_config

Lookup extended specifications in the config system at report.<report_config>.

Report Config

The config can contain any of the filter controls which will override any given value from the activity if a value is given.

Additional columns can also be specified, these are appended at the end of each line.

   cols:
     - head: Title put in the head columns
       cert: issuer_identifier
     - head: Just another title
       attribute: meta_email
     - head: Third column
       template: "[% attribute.meta_email %]"
     - head: The profile given in the CSR
       csr: profile

Each column definition should have a value for head that is printed in the reprt header to identify this column. Each column must have exactly one of the following keys that describes the content to display.

cert

Show the value of the named column from the certificate table. Available columns are:

subject

certificate_serial

csr_serial

identifier

status

notafter

notbefore

issuer_dn

issuer_identifier

subject_key_identifier

authority_key_identifier

csr

Show the value of the named column from the csr table, the only valid name is profile.

attribute

Show the value of the given attribute from the certificate_attributes table. If the given attribute is multivalued, the behaviour depends on the remaining report spec. If you have any other column that is using a template to render an attribute, you will see a single line with a random pick from the list of attributes. If you do not have such a column, you will get multiple lines for the same certificate, one for each value of the attribute.

template

The string is rendered with OpenXPKI::Template, the input paramaters are the columns of the cert as defined above in the key cert and all attributes as returned from get_cert_attributes API call as hash in the attribute key. Note that all attributes are lists, even if there are single valued!

Full example

Your activity definition:

    generate_report:
        class: OpenXPKI::Server::Workflow::Activity::Reports::Detail
        param:
            target_umask: 0644
            _map_target_filename: "expiry report [% USE date(format='%Y-%m-%dT%H:%M:%S') %][% date.format( context.valid_at ) %].csv"
            target_dir: /tmp
            report_config: expiry

Content of report/expiry.yaml inside realms config directory:

   cutoff_notafter: +000060
   include_expired: -000030
   cols:
     - head: Requestor eMail
       attribute: meta_email

This gives you a nice report about certificates which have expired within the last 30 days or will expire in the next 60 days with the contact email used while the request process.