Guardian News & Media
GNM RCS
Commission processing
Technical specification
Prepared by O3 Team Limited
Authors Nigel Robson
Creation date 03/09/2013
Document Ref. GNM_RCS_Commission_Processing_TS.docx
Version draft for review
.Introduction
Purpose
The document GNM_RCS_Commissions_FS.docx is the functional specification that describes what business functions RCS supports in relation to Commissioning content from contributors.
This document is one of a set of technical specifications that provide details of how those functions are implemented in RCS.
Scope
This document focusses on the commissioning process itself, including entry of the commission, issuing of confirmation letters, and tracking and reviewing of commissions during their lifecycle.
The fee approval and rights approval processes are covered in a separate document.
The various commission reporting functions are also covered in a separate document.
This document is intended as a high-level technical document outlining how the relevant business functions are implemented in terms of software modules.
Importantly, this document does not aim to provide the level of detail that would be required in a programming specification in areas such as program structure, detailed business rules, data integrity, validation, locking considerations, data security, and calls to/from other software modules, performance considerations, and so forth.
For details of program logic and coding, the reader should refer to the program files themselves.
Creating a new commission
Commissioning in advance
New commissions can be entered using this menu option: Commissions → New commission. This opens an Oracle Form named rcs_comm_070_pc.fmb
Step 1 – Search for the contributor
Enter the search criteria in the above screen and press the “Find…” button.
Step 2 – Identify the contributor
The user must highlight the contributor they want to commission from the search results.
Pressing the “Commiss…” button, or double-clicking the highlighted record, starts the entry of the commission:
Step 3 – Enter who the commission is being entered for
The user can choose on whose behalf they are entering the commission, or this step is skipped if they can only enter their own commissions:
Step 4 – Determine the format & pre-existence of the contribution
The user then identifies the format of the content to be delivered and whether it is newly created content or from the contributor’s existing stock.
A commission can only be for a single format, as chosen near the start of the commissioning process e.g. Text (for delivery of an article or blog), or Picture (for a photograph), and so on. Commissions cannot be defined as multi-format even though GNM has more recently started engaging contributors to submit text and images on the same subject.
NB Contracts can be multi-format, as described elsewhere in the Contracts documentation.
Step 5 – Determine the copyright status of the contribution
Lastly the user is prompted to say whether the copyright agreement is for a licence or an assignment of copyright.
All of the above decisions affect the standard set of rights that are applied to the commission once it is saved. The format choice also determines the nature of the fee e.g. lineage for text.
Step 6 – enter the commission details
At this point a screen is displayed into which the remaining commission details are entered, as shown below:
Retrospective commissioning
Retrospective commissions can be created in exactly the same way as described above, by changing the “Agreed on” date to a date in the past. Or a user can initiate the process from either of the Content matching screens by clicking on the item of unmatched content they wish to commission and pressing the “Create…” (a Commission) button as per the screen shots below of the content matching screens:
and…
This navigates the user to the “New commissions” screen as described above. The commissioning process remains the same, except that some of the commission details can be auto-completed for the user, including the Contribution (which is taken from the published Headline or Caption), the publication date, and the word count (for Text) or area for calculating image values.
When a commission is created this way it is immediately marked as being fulfilled as the link to the published content has already been made.
Commission details
Unique reference
Upon successfully entering a commission the system allocates a commission reference number (CRN) which uniquely identifies this contributor agreement. The CRN generated takes the form CXXXXX where the XXXXX component is an alphanumeric based on a value from a database sequence named COMM_ID. The generation of unique reference numbers across the system is described in the core technical documentation as the method is common to all automatically generated 6-letter references.
Contribution
The commissioning editor records the details of the contribution as this represents what the contributor has agreed to deliver, as follows:
the Agreed on date field reflects when the commission was agreed with the contributor. This affects the rights applicable – as GNM’s standard rights are subject to change over time;
the Contribution text field is entered;
the Due date is recorded; and
in the case of text the number of Words expected, delivered, of published.
NB the number of words agreed with the contributor may differ from the number they actually deliver, and this in turn may differ from the number of words published due to space constraints (in print) and as a result of sub-editing by the desk.
Publication date
A planned publication date should be entered, or the actual publication date when commissioning retrospectively.
Fees & Chart of accounts
Typically a single fee is payable for a commission once it has been fulfilled, but there are exceptions:
It is possible for there to be no fee due e.g. where GNM has been given content for free but a commission is still entered to record the rights acquired in that content; or
There may be a list or schedule of payments, including one or more of an Advance, a Fee on signature, a standard Fee, or a Spike fee.
Where no fee is due the user just ticks the Fee/No fee radio group button on the commission. Where multiple fees are due they can be maintained in this pop-up window:
RCS also records historical payments of Rights bonuses, and to a lesser extent Reuse fees. These fee types are no longer used.
Fees can be added to a commission on behalf of another user by clicking on the “On behalf of” button in the above window. The spend limit of these users determines whether the fee requires approval.
The currency in which fees should be paid is recorded against the commission.
Every commission is linked to codes that reflect the 8 segments of the GNM Chart of Accounts. When a commission is created not all segments are mandatory, although the Legal entity (segment 1) and Cost centre (segment 2) are. However all 8 segments must be completed before a payment instruction can be issued. Default values are populated into each segment where possible.
For more information on the Chart of Accounts segments please refer to the separate documents on that subject.
Rights
The rights applicable to all contractual relationships with contributors are quite complex. To save users from having to enter this mass of data it gets automatically created when the commission is first saved and can then be modified by the user. Pressing the Rights button displays the rights:
The detailed workings of the Rights model are not documented here as it is common to both Commissions and Contracts. It is documented in a separate Rights document.
Copyright Assignment (single vs. umbrella)
However one important area regarding commissions needs mentioning: Umbrella contracts and assignments. In some cases the first commission issued to a contributor is treated as an umbrella contract, and subsequent commissions will assume the terms of the umbrella contract. This process is usually followed if there is an assignment of copyright to GNM – the assignment is either a “Single assignment” or an “Umbrella assignment”.
Confirmation message
When the commission has been created the panel on the right hand side of the screen that previously displayed the contributor’s contact details is re-populated to display a text box that describes exactly what has just been agreed. The user should read through to this confirmation message, and if any errors are noticed they should be corrected.
Technical complexities
The screen rcs_comm_070_pc.fmb presents a number of challenges, and each solution is described below:
Search
The facilities to search for a contributor require complex queries to be constructed programmatically on PRE-QUERY for the ‘default where’ property of the LIST block. The LIST block is based on a view called CONTRIBUTORS which gets data from multiple tables.
Fees
The user is presented with a simple user interface to enter the commission fees, i.e. just a few fields. When the data is saved separate records are written to the COMMISSIONS table and COMMISSION_PAYMENTS table using an ON-INSERT and ON-UPDATE trigger in the COMM block.
Rights
A default set of rights are created for the commission, based upon the contributor type, content format, and copyright/licence arrangement agreed with the contributor. This is all managed by database triggers.
Font size
The font size in this screen is generally larger than elsewhere in the system, as it is used quite heavily and this makes it easier.
Canvas management
There is a significant and complicated set of code that determines which window and which canvas should be displayed (and which hidden) as a result of an given user action e.g. on commit, or when navigating through the commissioning process, on navigating back out of the process, on exiting a popup window, etc.
Reviewing & Tracking
Commissions can be reviewed and edited in two ways:
Review commissions (which shows commissions for a specific contributor);
Commission tracking (which shows commissions over a recent period of time).
Review commissions
All commissions for a contributor can been seen in the Review Commissions screen. On choosing this option from the menu the user is presented with a list of all contributors who have been commissioned from which they choose the one they want to look at. The screen then opens with all the commissions listed for that contributor, the most recent commission at the top.
This screen is accessed from this menu option: Commissions → Review commissions
This opens an Oracle Form named rcs_comm_010_pc.fmb
The fee fields shown above are summary fields reflecting the total of each fee type in the detailed schedule of fees. Clicking on any of these fee fields opens the popup window listing all fees (as described in an earlier section). It is in this popup window that fees are added or amended.
Expense payments can be added to a commission in this screen by pressing the “Expenses” button. Because the same facility is available for Contracts the subject of expenses is explained in separate documentation rather than being repeated in both the commissions and contracts documents.
If the content being bought is a Book extract then the details of this are recorded in a popup window accessed by pressing the “Buy-in…” button. Book extracts are processed in a different way, by the Rights department, and so they are documented separately.
.
Commission tracking
The commission tracking screen lists all recent commissions.
The screen shows all live commissions from the last 56 days, as well as 28 days of cancelled commissions. These durations are defined as system parameters that can be adjusted by the RCS Administrator.
This screen is accessed from this menu option: Commissions → Commissions tracking
This opens an Oracle Form named rcs_comm_060_pc.fmb
The user can restrict the commissions shown by date using the radio group options in the top right of the screen.
NB This screen is run in 3 modes in RCS i.e. the physical form rcs_comm_060_pc.fmb can be thought of as 3 logical forms, namely (1) Unreturned single assignments, (2) Commission tracking, and (3) Forthcoming book extracts. It has been designed to inherit as much as possible from other *comm* forms to reduce the amount of code that needs to be maintained, and to maintain a consistent look and feel.
Commission letters
By default all contributors receive a commission letter for each commission they agree to undertake. The commission letter confirms the terms they have agreed, including the contribution, fees and rights.
A contributor can request not to receive confirmation letters: if they do so a flag can be set in the relevant Contributor screen to prevent any more being sent.
Contributors may also request that their confirmation letters be sent their agent: this can be set in any of the commission screens.
Commission letters are withheld until the rights and fees have been approved.
Commission letters are issued once the following criteria have been met:
The Confirmation sent? checkbox has not been checked i.e. it is unsent;
The commission is not spiked, or was agreed after 1st Sept 2010
The rights agreed reflect (a) a licence, or (b) a single assignment or assignment from a staffer, or (c) an umbrella assignment which either has an issued date and returned date or the contributor has no prior commission that was an umbrella assignment;
The commission is not cancelled;
The right are approved;
The commission is not a Book extract; and
If commission payments exist they must approved, or the commission is designated No fee.
The confirmation letter that is issued consequently fall into these broad classifications
Licences – where no signature is required;
Single assignments – where a signature is required; and
Umbrella assignments – signature is required for first commission, no signature thereafter.
Book extracts are not processed with a commission letter, but instead a separate term sheet.
Letter production
If the designated confirmation recipient has an email address then the commission letter is produced as a PDF report on the application server by an Oracle Report (named rcs_comm_010.rdf). The creation of the report is triggered by a database job that polls for commission letters that need to be issued.
The design solution behind this is called “Event driven publishing” and is common to a number of areas of the system. It is documented in a separate core Technical Reference manual, and so is not further documented here.
If the recipient does not have an email address then the report is initiated manually by the RCS Administrator using this menu option:
Rights → Commission letters
This initiates the report, and a single PDF is created containing all the outstanding letters that need to be posted. Page throws are inserted into the report to ensure it can be printed double-sided without 2 separate letters being on opposing sides of the same physical sheet of paper.
The RCS Administrator prints, folds, and envelopes these letters for posting.
Letter archives
Letters produced in batch are filed into year and month folders and compressed into zip archives on the server. This is done via a Windows script run from a Command Window.
The letters printed manually for posting are archived separately by the RCS Administrator after they have been printed.
In recent times all letters produced in batch have been saved to the database against the commission record. Details of this document storage solution are the subject of a separate Technical Reference manual as the technique is again one that is repeated across the system.
Letter content
The report producing the commission letters contains a lot of complex processing that undergoes changes most years as the business requirements change. The report queries a view called COMMISSION_LETTERS. Using a view is beneficial as it means some changes to the report can be made by simply changing the view. The view is also used by the process that looks for letters waiting to be sent, and also by a count on the Welcome screen that advises the RCS Administrator that there are letters to print and post. Any change to the view is therefore reflected in all three places.
In some aspects the letter can be thought of as a mail merge document, with name, address and commission details being queried and then presented in the report’s layout fields.
Where data needs to be merged into sentences hidden fields are used that source the data from the relevant query group. These fields are then referenced in the visible boiler plate text.
In other parts of the report different paragraphs are used depending on which content format is being commissioned or whether the recipient of the report is the contributor or their agent. In some cases this is achieved by having format triggers on Frames or Fields which determine which Frames or Fields to hide and which to show. In other cases Formula columns are defined in the report Data Model in which a PL/SQL function returns the data required based on the data queried for the commission being processed. The formula column is then set as the source of a Field in the layout.
Book extracts
Book extract commissions are not confirmed with the contributor using the same letter; instead a separate contract (term sheet) is issued. Book extracts follow a different process, managed within the Rights department by the Rights manager, and are documented separately.
Fulfilment, spiking, cancellation
The lifecycle of a commission ends when it is paid or cancelled.
Normally a contributor fulfils his/her obligation under a commission by delivering the requested content to GNM. At this point the commission can be marked as fulfilled. Frequently the commission is not marked as fulfilled upon delivery but instead when the content is published and matched (linked back) to the commission, as this process requires less administration effort.
Commissions can be manually fulfilled by pressing the “Fulfil” button in the Review commissions screen – this is important for stock building desks such as Features and Obituaries where the contributor should not have to wait for publication.
Payment is triggered by fulfilment of the commission.
Payment may also be triggered if the commission is spiked (i.e. the delivered content is no longer going to be published for whatever reason). Commissions are spiked by pressing the “Spike” button in the Review commissions screen and a full or part fee paid.
Commissions can be cancelled – usually because they were entered in error – by pressing the “Cancel” button in the Review commissions screen. No fees are payable when a commissions is cancelled.
Audit controls
Created & last modified audit
All commission records are stamped with the username of the user who entered the data, and the date and time it was saved.
Thereafter, whenever commission data is changed the record is stamped with the username of the user who changed the data, and the date and time the changes was saved.
The same applies to all subordinate data recorded against the commission, including fees, rights, and creative contributors and so on.
Change history
A change history is kept of all changes to important commissions data. The old and new values are stored, along with the username of the user who changed the data, and the date and time the change occurred. This is NOT visible to the users.
This data is useful as an audit trail and for reverting incorrect changes to the data.
End of Document